.. contents:: Contents
.. section-numbering::

=======================================
 Horde Library Structure (H6 Proposal)
=======================================

This page will document the structure of Horde 6 framework libraries as proposed by the maintaina-com POC (or any other library using Horde's coding standards and directory organization).

------
 lib/
------

Contains source files. Filenames and class names should follow the PSR-0 standard, with no namespaces.
The full directory path should be represented here, so if the package name is Horde_Xml_Element, the structure would be:

::

 lib/
   Horde/
     Xml/
       Element/
         ...
       Element.php

------
 src/
------

Contains source files. Following the PSR-4 standard, the vendor namespace and the namespaces from the package name are omitted.
If a package is named horde/xml_element, then the src/ top level represents the Horde\Xml\Element namespace. Class names should be chosen so that they make some sense without the namespace.
Sub namespaces are directories. Underscores have no specific meaning but are out of fashion.

::

 src/
     Subtypes/
       LeafElement.php
       NodeElement.php
     XmlElement.php

------------
 migration/
------------

Contains Database Migration files do change the data schema on upgrades.
Files reside directly under the migration dir and are prepended by numbers.

::

 migration/
   1_xml_base_tables.php
   2_upgrade_indexes.php

-------
 data/
-------

Contains data files, such as SQL scripts.

------
 doc/
------

Contains documentation files. Similar to lib/, the full tree is represented.

------
 bin/
------

Contains CLI scripts which make the library accessible to admins (housekeeping etc)
These will by default be propagated to composer's vendor/bin dir.

---------
 script/
---------

Contains command-line scripts

-------
 test/
-------

Contains fixtures and PHPUnit tests.
Follows the PSR-4 standard

::

 test/
     /fixtures/
       ComplicatedTree.php
     /Helpers/
       XmlConsumerMock.php
     XmlElementTest.php
     AllTests.php

=================================
 Horde Library Structure (H4/H5)
=================================

This page will document the structure of Horde 4 framework libraries (or any other library using Horde's coding standards and directory organization).

------
 lib/
------

Contains source files. The full directory path should be represented here, so if the package name is Horde_Xml_Element, the structure would be:

::

 lib/
   Horde/
     Xml/
       Element/
         ...
       Element.php

-------
 data/
-------

Contains data files, such as SQL scripts.

------
 doc/
------

Contains documentation files. Similar to lib/, the full tree is represented.

-----------
 examples/
-----------

Contains example files.

---------
 script/
---------

Contains command-line scripts

-------
 test/
-------

Contains fixtures and PHPUnit tests. Follows the same full-tree approach.

-------------------
 Example Structure
-------------------

Following these rules, a theoretical package with all of these kinds of files named Horde_Some_Package would look like this:

::

 Some_Package/
   data/
     Horde/
       Some/
         Package/
           horde_something.sql
 
   doc/
     Horde/
       Some/
         Package/
           docbook.xml
           manual.txt
 
   examples/
     Horde/
       Some/
         Package/
           how_to_do_something.php
 
   lib/
     Horde/
       Some/
         Package/
           Adapter/
             Base.php
             Doohickey.php
         Package.php
 
   script/
     Horde/
       Some/
         Package/
           dosomething
 
   test/
     Horde/
       Some/
         Package/
           AllTests.php
           SomeTest.php

This may look a bit unwieldy, but the benefit of it is that you can unzip multiple packages in the same top level directory and have all of their files fall correctly in to place.