Which directory structure / naming convention do you prefer?

[trq]

I think I already know the answer to this question myself but would appreciate some other developers opinions. For whatever reason, I changed Proem's naming convention about 2 months ago and now, I'm starting to think it was a mistake.

 

The current directory structure looks like:

 

lib/Proem/Api/
├── Bootstrap
│   ├── Filter
│   │   └── Event
│   │       ├── Dispatch.php
│   │       ├── Request.php
│   │       ├── Response.php
│   │       └── Route.php
│   └── Signal
│       └── Event
│           └── Bootstrap.php
├── Controller
│   ├── Standard.php
│   └── Template.php
├── Dispatch
│   ├── Stage.php
│   ├── Standard.php
│   └── Template.php
├── Ext
│   ├── Module
│   │   └── Generic.php
│   ├── Plugin
│   │   └── Generic.php
│   └── Template.php
├── Filter
│   ├── Event
│   │   ├── Generic.php
│   │   └── Template.php
│   └── Manager
│       ├── Standard.php
│       └── Template.php
├── IO
│   ├── Request
│   │   ├── Http
│   │   │   ├── Fake.php
│   │   │   └── Standard.php
│   │   └── Template.php
│   └── Response
│       ├── Http
│       │   └── Standard.php
│       └── Template.php
├── Proem.php
├── Routing
│   ├── Route
│   │   ├── Generic.php
│   │   ├── Payload.php
│   │   ├── Standard.php
│   │   └── Template.php
│   ├── Router
│   │   ├── Standard.php
│   │   └── Template.php
│   └── Signal
│       └── Event
│           ├── RouteExhausted.php
│           └── RouteMatch.php
├── Service
│   ├── Asset
│   │   ├── Standard.php
│   │   └── Template.php
│   └── Manager
│       ├── Standard.php
│       └── Template.php
├── Signal
│   ├── Event
│   │   ├── Standard.php
│   │   └── Template.php
│   └── Manager
│       ├── Standard.php
│       └── Template.php
└── Util
    ├── ArrayHelper.php
    ├── Opt
    │   ├── Option.php
    │   ├── Options.php
    │   └── Payload.php
    ├── Process
    │   └── Callback.php
    └── Storage
        ├── KeyValStore.php
        └── Queue.php

 

The original structure was:

 

lib/Proem/Api/
├── Asset
│   └── Manager.php
├── Asset.php
├── Autoloader.php
├── Chain
│   └── Event.php
├── Chain.php
├── Event
│   └── Manager.php
├── Event.php
├── Proem.php
└── Util
    ├── Callback.php
    ├── Options
    │   └── Option.php
    ├── Options.php
    └── Queue.php

 

Now, besides the obvious massive growth of the code base, you can see that the change means there are a lot of classes with the same names in the newer convention. This means I end up needing to alias a lot of classes when I bring them into the same namespace. It also means the API docs can be harder to follow.

 

Anyway, if anyone has some input on which they prefer (or any better ideas) it would be appreciated. I'm pretty sure I'm looking at a massive overhaul here, and not looking forward to it. Ah, the mistakes you make huh?

 

Oh and ps: I should mention that all the Template files are Interfaces while Standard are the base abstract classes that implement them.

 

I guess my main motivation for changing the layout was that I hate repeated words within a namespace. Things like Proem\Events\Event\EventManager bug me.

[Hall of Famer]

Well I am not an advanced programmer yet, so at this point I still havent incorporated MVC for my project. Heres the directory structure of my project, Id say its somewhere between beginners and advanced, intermediate maybe?

 

--admincp

 

--classes

----abstracts

----interfaces

----traits

 

--css

 

--fonts

 

--functions

 

--includes

----3rdparty

----lang

 

--install 

 

--js

 

--images

 

--templates

 

And then goes every presentation-layor script files such as index.php, register.php, login.php and so on.

[trq]

Proem is a framework, I probably should have pointed that out. A project directory structure is completely separate.

[requinix]

I'm not sure how much I can comment on what you have now but I think I like the current structure more than the original. It took me a while to realize that namespaces aren't just about class paths but about grouping of classes; to take what I have as an example, /Mvc/Controls/Control.php (\Mvc\Controls namespace, Control class) makes more sense to me than /Mvc/Control.php (\Mvc namespace, Control class).

 

Couple other miscellaneous comments on what I do:

- I also name interfaces as IInterface and traits as TTrait (I'm writing for 5.4) so it's obvious what things are

- I even name files as (class|interface|trait).name.php, but it's the first time I've done something like that so I might change that later

 

I don't have very many files to show off as the current version of my framework is still quite young and very specialized, but here's my version of the original (and shorter) file list:

/lib/Proem/Api
- /Assets
  - class.Asset.php (abstract? base class of IAsset)
  - class.AssetManager.php
  - interface.IAsset.php
- /Chains
  - class.Chain.php (abstract? base class of IChain)
  - class.ChainEvent.php
  - interface.IChain.php
- /Events
  - class.Event.php (abstract? base class)
  - class.EventManager.php
- /Utility
  - /Options
    - class.Option.php (abstract? base class)
    - class.OptionsCollection.php (convention I've borrowed from .NET)
  - class.Callback.php
  - class.Queue.php
- class.Autoloader.php
- Proem.php (sounds like a bootstrap/prepend file)

[Philip]

I agree, I like the current more than the original

[trq]

Maybe I haven't been clear enough with my post. The current issue is not so much about the directory structure itself, but the fact that you can (and do) end up with numerous filename collisions.

 

As an example, the Proem object currently depends on (amongst other things) the filter manager (named Standard), the service manager (named Standard) and the signal manager (again named Standard).

 

Because all of the classes are named Standard they need to be aliased. eg;

 

use Proem\Service\Manager\Standard as ServiceManager,
    Proem\Signal\Manager\Standard as SignalManager,
    Proem\Filter\Manager\Standard as FilterManager;

 

Now, if these classes where named more like they where in the previous incarnation they would already have names such as Servicemanager, SignalManager and FilterManager.

 

This is my main concern and is something that I can see turning other developers off from using Proem. Any thoughts on this subject would be much appreciated.

[johnny86]

I've given up a lot of thought on directory structures due to my personal project (a framework, what a surprise). I decided to go with full PHP 5.4 so earlier versions would not be supported.

 

I ended up mapping namespaces to directories which is pretty obvious. That is all the framework itself understands and is as simple as it gets. I see no need for other kind of naming or structure. Developers may off course add their own extended loaders for the autoloader if needed.

 

The structure under library is as follows (this is just imaginary):

 

FWNAME means frameworks name so in your case I'd do Proem / Proemi / Proema / Proemt

 

- /library

      - /FWNAME

            - /Validator

                  - Email.php // Implementation

      - /FWNAMEA

            - /Validator

                  - Something.php // Abstract class which can be extended to do something more complex maybe

      - /FWNAMEI

            - Validator.php // Validator interface which all implementations have to implement. Abstract classes are kind of templates

      - /FWNAMET

            - /Utility

                  - ArrayMethods.php // Trait which have utility methods for arrays

 

 

So the idea was to just put Implementations, Abstract classes, Interfaces and Traits under different directories in library.. I think it keeps the structure very clear on where everything is and I (or developers) don't need to use some prefixes in classnames or files etc. Every class has it's own namespace so there should not be collisions in class names since Controller\Standard is different from Dispatch\Standard. The namespaces are declared right at the begining of every file.

 

What are your thoughts on that?

 

Modify:

If I'm missing something here please let me know =)

I think that you can safely bring(use) those classes in(to) a same namespace together because they'll still have their own namespaces and are instantiated using the namespaces. A developer may off course make own aliases to reference them..

[Adam]

I think you could have a trade-off between the two. I prefer how it is now, obviously because the classes are better organised. Do you need such deep levelled namespaces though?

 

For example:

 

├── IO

│  ├── Request

│  │  ├── Http

│  │  │  ├── Fake.php

│  │  │  └── Standard.php

│  │  └── Template.php

│  └── Response

│      ├── Http

│      │  └── Standard.php

│      └── Template.php

 

Why not alter the structure slightly by grouping the request and response classes under a Http namespace..?

 

+-- IO

¦  +-- Http

¦  ¦  +-- Request.php

¦  ¦  +-- Request

¦  ¦  ¦  +-- Fake.php

¦  ¦  +-- Response.php

 

You still have well organised classes, but remove the need for generic names.

[Adam]

On the topic of interfaces by the way, I think they're better describing the behaviour as opposed to following the naming convention of the class that implements them. For example the native "Iterator" interface, or in the context of Proem you could have the Router implement Routable, or something. Again just gets rid of generic names and doesn't necessarily tie it to any single class.

[requinix]

Because all of the classes are named Standard they need to be aliased. eg;

 

use Proem\Service\Manager\Standard as ServiceManager,
    Proem\Signal\Manager\Standard as SignalManager,
    Proem\Filter\Manager\Standard as FilterManager;

 

Now, if these classes where named more like they where in the previous incarnation they would already have names such as Servicemanager, SignalManager and FilterManager.

That's what I'd do. Not just for the name collision: if you used just one of those somewhere you'd have to alias it anyways because a name like "Standard" isn't helpful.

use Proem\Service\StandardServiceManager, // unless there's a lot of Managers I'd remove the namespace level for them
    Proem\Signal\StandardSignalManager,
    Proem\Filter\StandardFilterManager;

(though personally for those types of classes I prefer a -Base suffix over a Standard- prefix, like ServiceManagerBase, if even anything at all)

[scootstah]

I think you could have a trade-off between the two. I prefer how it is now, obviously because the classes are better organised. Do you need such deep levelled namespaces though?

 

For example:

 

├── IO

│  ├── Request

│  │  ├── Http

│  │  │  ├── Fake.php

│  │  │  └── Standard.php

│  │  └── Template.php

│  └── Response

│      ├── Http

│      │  └── Standard.php

│      └── Template.php

 

Why not alter the structure slightly by grouping the request and response classes under a Http namespace..?

 

+-- IO

¦  +-- Http

¦  ¦  +-- Request.php

¦  ¦  +-- Request

¦  ¦  ¦  +-- Fake.php

¦  ¦  +-- Response.php

 

You still have well organised classes, but remove the need for generic names.

 

I agree, that looks a lot neater.