Answers.Body: <p>In general, when developing extensions I would take a look at the existing ones authored by the core team or by heavily active contributors. To give some importance on my suggestion below I just checked widely used cms independent extensions available and landed at <a href="https://github.com/dlobo/org.civicrm.module.cividiscount" rel="nofollow noreferrer">https://github.com/dlobo/org.civicrm.module.cividiscount</a>. </p>
  
  <p>Extensions that I wrote and most I know hold classes under <code>&lt;tld.domain.ext&gt;/CRM/ExtensionName/</code> and follow php's naming conventions there. API methods are located under <code>api/v3/</code> and named in api manner (classes reflecting api, methods reflecting actions).   </p>
  
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2016-12-28T03:03:20.100Z
Answers.Text: Thanks @Neilo - I'm just wondering about best practice since php 5.3 became standard and introduced namespacing. (see the comments [here](https://wiki.civicrm.org/confluence/display/CRMDOC/The+codebase#Thecodebase-Namespaces) that imply a new pattern but aren't clear on if it applies to extensions or not.
Answers.UserDisplayName: ErichBSchulz
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2016-12-29T22:20:22.717Z
Answers.Text: Jesus, sorry! Reading the "When to use" column in the doc you linked I dare to say  I'd know what to use in *my* extensions. But my suggestions wouldn't be more than hardly educated guesses. A question for more advanced people.
Answers.UserDisplayName: nielo
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2016-12-27T22:07:50.927Z
Answers.LastActivityDate: 2016-12-27T22:07:50.927Z
Answers.UserDisplayName: nielo
Answers.Body: <h2>The conventional approach</h2>
  
  <p>Generally, the safe play is to make a file like <code>&lt;myextension&gt;/CRM/MyExtension/MyClass.php</code>:</p>
  
  <pre><code>&lt;?php
  class CRM_MyExtension_MyClass { ...}
  </code></pre>
  
  <p>(Be sure to match the capitalization of files and classes.)</p>
  
  <p>Most documentation and tooling is based on <code>CRM_*</code> conventions, and a handful of things in core (such as <code>civicrm_payment_processor_type.class_name</code>) make quirky assumptions which only work with <code>CRM_*</code> classes.</p>
  
  <p><em>How it works</em>: In civix-based extensions, the default <code>hook_civicrm_config</code> adds your extension to the <code>include_path</code>. The classloader <code>CRM_Core_ClassLoader</code> searches the <code>include_path</code> automatically for <code>CRM_*</code> classes.</p>
  
  <p><em>Critique:</em> In older PHP projects, it was common to automatically link the class-loading with the <code>include_path</code>, but in large codebases this can lead to a large number of file-system checks. Now-a-days many frameworks will reduce lookups by pre-generating some kind of map (namespaces&lt;=>directories or classes&lt;=>files).</p>
  
  <h2>The PSR-4 approach (Civi v4.7+)</h2>
  
  <p>PSR-4 is a more contemporary technique in which you explicitly map a directory to a namespace. Many PHP developers have been exposed to <a href="https://seld.be/notes/psr-4-autoloading-support-in-composer" rel="nofollow noreferrer">PSR-4 through <code>composer.json</code></a>. Civi v4.7 adds <code>CRM_Extension_ClassLoader</code>; with this, you can use <code>info.xml</code> to declare similar mappings:</p>
  
  <pre><code>&lt;extension key="..." type="module"&gt;
    ...
    &lt;classloader&gt;
      &lt;psr4 prefix="My\Namespace\" path="src" /&gt;
    &lt;/classloader&gt;
    ...
  &lt;/extension&gt;
  </code></pre>
  
  <p>In this case, the file <code>&lt;myextension&gt;/src/Foo.php</code> would look like:</p>
  
  <pre><code>&lt;?php
  namespace My\Namespace;
  class Foo { ... }
  </code></pre>
  
  <p>In terms of lookup performance and caching, this should be better than <code>CRM_Core_ClassLoader</code>. However, it doesn't have full parity with <code>CRM_*</code> in terms of documentation / tooling / testing.</p>
  
  <h1>Custom class loader</h1>
  
  <p>You should be able to register your own class-loaders -- e.g. just call <code>spl_autoload_register(...)</code> in your module's main PHP file (perhaps in <code>hook_civicrm_config</code>). If you do this, I suggest following a convention like PSR-0 or PSR-4.</p>
  
  <p>Compared to the PSR-4/Civi v4.7 approach above:</p>
  
  <ul>
  <li>Pro: Should be compatible with any version of Civi</li>
  <li>Con: Requires more lines of code</li>
  <li>Con: Has the same issue of negligible documentation / tooling / testing</li>
  </ul>
  
  <h1>PHPUnit Base Classes</h1>
  
  <p>There is an issue if you want to write a custom base-class for PHPUnit tests within an extension -- which is the topic of <a href="https://civicrm.stackexchange.com/questions/15810/does-class-autoloading-not-work-in-standalone-phpunit-testing">Does class autoloading not work in standalone phpunit testing?</a></p>
  
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2016-12-28T05:55:58.590Z
Answers.Text: Thanks Tim, so since I'm on 4.6 currently path of least resistance is `The conventional approach` then? There's no standard backport example for 4.6 laying about?
Answers.UserDisplayName: ErichBSchulz
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2016-12-28T06:15:55.340Z
Answers.Text: sorry I know I could nut this out but if i do my own home grown I will exacerbate the "negligible documentation / tooling / testing" problem!
Answers.UserDisplayName: ErichBSchulz
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2016-12-28T04:31:00.677Z
Answers.LastActivityDate: 2016-12-28T06:11:42.153Z
Answers.LastEditDate: 2017-04-13T12:53:13.167Z
Answers.UserDisplayName: Tim Otten
Body: <p>Noting these related questions 
  (<a href="https://civicrm.stackexchange.com/questions/3203/where-to-put-api-wrapper-class-in-an-extension">1</a>
  <a href="https://civicrm.stackexchange.com/questions/15810/does-class-autoloading-not-work-in-standalone-phpunit-testing">2</a>
  <a href="https://civicrm.stackexchange.com/questions/11357/how-to-develop-extension-that-relies-on-libs-brought-in-by-composer">3</a>)
  and these two wiki pages
  (<a href="https://wiki.civicrm.org/confluence/display/CRMDOC/Create+a+Module+Extension" rel="nofollow noreferrer">1</a>
  <a href="https://wiki.civicrm.org/confluence/display/CRMDOC/The+codebase#Thecodebase-Namespaces" rel="nofollow noreferrer">2</a>)
  and the <a href="http://www.php-fig.org/psr/psr-0/" rel="nofollow noreferrer">psr-0 standard</a>, I remain a bit lost about current best practice in CiviCRM extensions!</p>
  
  <p>So if I have an extenstion <code>org.goodfolk.magichtml</code></p>
  
  <p>Would I put my classes in</p>
  
  <pre><code>org.goodfolk.magichtml/Civi/MagicHtml/
  </code></pre>
  
  <p>So in <code>org.goodfolk.magichtml/Civi/MagicHtml/HtmlFlash.php</code> I would have the following:</p>
  
  <p><code>
      &lt;?php
      namespace org.goodfolk.magichtml/MagicHtml;
      class HtmlFlash {
        public function squirmLeft() {};
        public function squirmRight() {};
      }
  </code></p>
  
  <p>Is that correct?</p>
  
  <p>or can it be simplified to:</p>
  
  <p><code>org.goodfolk.magichtml/Civi/HtmlFlash.php</code>:</p>
  
  <p><code>
      &lt;?php
      namespace org.goodfolk.magichtml;
      class HtmlFlash {
        public function squirmLeft() {};
        public function squirmRight() {};
      }
  </code></p>
  
Comments.ContentLicense: CC BY-SA 3.0
Comments.CreationDate: 2016-12-27T01:45:01.943Z
Comments.Text: note I deliberately put multiword class and extension in the example as I'd like to clarity capitalization and underscore patterns too
Comments.UserDisplayName: ErichBSchulz
Comments.ContentLicense: CC BY-SA 3.0
Comments.CreationDate: 2016-12-27T01:58:13.577Z
Comments.Text: and proper handling html/HTML/Html (which also relates to SQL, API, PDF etc etc etc)
Comments.UserDisplayName: ErichBSchulz
Tags: <php><best-practice><coding-standards><autoloading>
Title: Class naming and namespaces: best practice as an extension author?
ThreadText: # Class naming and namespaces: best practice as an extension author?
  
  (Asked by: username_0 on 2016-12-27)
  
  Noting these related questions 
  (1
  2
  3)
  and these two wiki pages
  (1
  2)
  and the psr-0 standard, I remain a bit lost about current best practice in CiviCRM extensions!
  So if I have an extenstion org.goodfolk.magichtml
  Would I put my classes in
  org.goodfolk.magichtml/Civi/MagicHtml/
  
  So in org.goodfolk.magichtml/Civi/MagicHtml/HtmlFlash.php I would have the following:
  
  
  Is that correct?
  or can it be simplified to:
  org.goodfolk.magichtml/Civi/HtmlFlash.php:
  
  **Tags:** php, best-practice, coding-standards, autoloading
  
  > **Comments:**
  > **username_0**: note I deliberately put multiword class and extension in the example as I'd like to clarity capitalization and underscore patterns too  
  > **username_0**: and proper handling html/HTML/Html (which also relates to SQL, API, PDF etc etc etc)  
  
  ---
  
  ## 2 answers
  
  ### Answer by username_2 on 2016-12-28. Score: 5 | Accepted answer
  
  The conventional approach
  Generally, the safe play is to make a file like /CRM/MyExtension/MyClass.php:
  
  (Be sure to match the capitalization of files and classes.)
  Most documentation and tooling is based on CRM_* conventions, and a handful of things in core (such as civicrm_payment_processor_type.class_name) make quirky assumptions which only work with CRM_* classes.
  How it works: In civix-based extensions, the default hook_civicrm_config adds your extension to the include_path. The classloader CRM_Core_ClassLoader searches the include_path automatically for CRM_* classes.
  Critique: In older PHP projects, it was common to automatically link the class-loading with the include_path, but in large codebases this can lead to a large number of file-system checks. Now-a-days many frameworks will reduce lookups by pre-generating some kind of map (namespaces<=>directories or classes<=>files).
  The PSR-4 approach (Civi v4.7+)
  PSR-4 is a more contemporary technique in which you explicitly map a directory to a namespace. Many PHP developers have been exposed to PSR-4 through composer.json. Civi v4.7 adds CRM_Extension_ClassLoader; with this, you can use info.xml to declare similar mappings:
  
    ...
    
      
    
    ...
  
  
  In this case, the file /src/Foo.php would look like:
  
  In terms of lookup performance and caching, this should be better than CRM_Core_ClassLoader. However, it doesn't have full parity with CRM_* in terms of documentation / tooling / testing.
  Custom class loader
  You should be able to register your own class-loaders -- e.g. just call spl_autoload_register(...) in your module's main PHP file (perhaps in hook_civicrm_config). If you do this, I suggest following a convention like PSR-0 or PSR-4.
  Compared to the PSR-4/Civi v4.7 approach above:
  
  Pro: Should be compatible with any version of Civi
  Con: Requires more lines of code
  Con: Has the same issue of negligible documentation / tooling / testing
  
  PHPUnit Base Classes
  There is an issue if you want to write a custom base-class for PHPUnit tests within an extension -- which is the topic of Does class autoloading not work in standalone phpunit testing?
  
  > **Comments:**
  > **username_0**: Thanks Tim, so since I'm on 4.6 currently path of least resistance is `The conventional approach` then? There's no standard backport example for 4.6 laying about?  
  > **username_0**: sorry I know I could nut this out but if i do my own home grown I will exacerbate the "negligible documentation / tooling / testing" problem!  
  
  ---
  
  ### Answer by username_1 on 2016-12-27. Score: 0
  
  In general, when developing extensions I would take a look at the existing ones authored by the core team or by heavily active contributors. To give some importance on my suggestion below I just checked widely used cms independent extensions available and landed at <https://github.com/dlobo/org.civicrm.module.cividiscount>.
  
  Extensions that I wrote and most I know hold classes under `/CRM/ExtensionName/` and follow php's naming conventions there. API methods are located under `api/v3/` and named in api manner (classes reflecting api, methods reflecting actions).
  
  > **Comments:**
  > **username_0**: Thanks @Neilo - I'm just wondering about best practice since php 5.3 became standard and introduced namespacing. (see the comments [here](https://wiki.civicrm.org/confluence/display/CRMDOC/The+codebase#Thecodebase-Namespaces) that imply a new pattern but aren't clear on if it applies to extensions or not.  
  > **username_1**: Jesus, sorry! Reading the "When to use" column in the doc you linked I dare to say  I'd know what to use in *my* extensions. But my suggestions wouldn't be more than hardly educated guesses. A question for more advanced people.  
  
  ---
  
  