Naming Recommendation for Controllers, Actions, and URLs using zend_controller

[Dennis Fogg]

Given the zend_controller naming changes in zend framework 1.5, I’m trying to figure out a recommended naming scheme that I can use for zf 1.5 and onwards.  This forum post helped a lot: http://www.nabble.com/AW%3A-Normalizing-action-function-names-p16110540.html but it does not mention multi-word controllers and file and directory names.  Here’s what I could figure out.   Comments?

The formatted prose is on this wordpress blog post because nabble would not keep my MS Word formatting (sorry for the inconvenience, but it's much, much easier to read this way ).

Here's some snippets from that formatted post:

url: domain.com/controller-name/action-name
Controller File name / Class name: MixedCase  
  eg: file RoadMapController.php contains class RoadMapController for url domain.com/road-map
View Action method: Use camelCase
  Eg: componentsForHighLevelAction for domain.com/road-map/components-for-high-level
View File and directory:
  Controller directory: All lower case with dashes between words.  
  View file name:  All lower case with dashes between words.  
  Eg: my_file_system/road-map/components-for-high-level.phtml

This naming scheme is pretty complicated.  It sure would be nice to have a complete example explicitly documented in the zend_controller reference guide.  I’m really looking for the zend framework recommendation on setting this up such that it covers the common cases, enables readable (word separated) URLs, and will be stable for future releases.  Well, this is my attempt at documenting it.

[weierophinney]

-- Dennis Fogg <[hidden email]> wrote
(on Friday, 28 March 2008, 02:53 PM -0700):
>
> Given the zend_controller naming changes in zend framework 1.5, I’m trying to
> figure out a recommended naming scheme that I can use for zf 1.5 and
> onwards.  This forum post helped a lot:
> http://www.nabble.com/AW%3A-Normalizing-action-function-names-p16110540.html 
> http://www.nabble.com/AW%3A-Normalizing-action-function-names-p16110540.html 
> but it does not mention multi-word controllers and file and directory names.
> Here’s what I could figure out.   Comments?

There *were* no changes; only enforcement of the documented standards.

Let's cut to the chase:

  * Your controllers and actions can have camelCasing to accomodate
    multiple words
  * ON THE URL, you must specify multiple words using a word separator
    ('.' or '-')
  * VIEW SCRIPTS follow the same conventions as URLs

What was changed in 1.5.0? Well, we've fielded a large number of
questions from people who were noting that when using camelCasing for
action names, view scripts were not always resolving. Why? because the
view script that was looked up would be different based on whether or
not they used camelCasing on the URL -- and whether or not they were
following the recommendations for naming their view scripts.

The issue is that PHP is case insensitive when it comes to
function/method names. So a url of 'iAmCamelCased' would be inflected in
the dispatcher to dispatch the iamcamelcased() method -- which would
execute the same as if they url 'i-am-camel-cased' was called (which
maps to iAmCamelCased()' -- both are valid ways to call the method.
However, on the view end, we do the same normalization that the
dispatcher does -- which means you have two very differently named
scripts: iamcamelcased.phtml vs i-am-camel-cased.phtml.

Since we already had a documented standard, we chose to enforce it at
the code level, to ensure that there is clarity and consistency between
how the URL resolves to both an action and a view script.

So, it's very simple: follow the rules as outlined above, and you're
good to go.

> The formatted prose is on
> http://develop2travel.wordpress.com/2008/03/28/naming-recommendation-for-controllers-actions-urls-using-zend_controller/
> this wordpress blog post  because nabble would not keep my MS Word
> formatting (sorry for the inconvenience, but it's much, much easier to read
> this way ).
>
> Here's some snippets from
> http://develop2travel.wordpress.com/2008/03/28/naming-recommendation-for-controllers-actions-urls-using-zend_controller/
> that formatted post :
>
> url: domain.com/controller-name/action-name
> Controller File name / Class name: MixedCase  
>   eg: file RoadMapController.php contains class RoadMapController for url
> domain.com/road-map
> View Action method: Use camelCase
>   Eg: componentsForHighLevelAction for
> domain.com/road-map/components-for-high-level
> View File and directory:
>   Controller directory: All lower case with dashes between words.  
>   View file name:  All lower case with dashes between words.  
>   Eg: my_file_system/road-map/components-for-high-level.phtml
>
> This naming scheme is pretty complicated.  It sure would be nice to have a
> complete example explicitly documented in the zend_controller reference
> guide.  I’m really looking for the zend framework recommendation on setting
> this up such that it covers the common cases, enables readable (word
> separated) URLs, and will be stable for future releases.  Well, this is my
> attempt at documenting it.
>
> --
> View this message in context: http://www.nabble.com/Naming-Recommendation-for-Controllers%2C-Actions%2C-and-URLs-using-zend_controller-tp16362913p16362913.html
> Sent from the Zend Framework mailing list archive at Nabble.com.
>

--
Matthew Weier O'Phinney
PHP Developer            | [hidden email]
Zend - The PHP Company   | http://www.zend.com/

[Dennis Fogg]

Matthew Weier O'Phinney-3 wrote:

Let's cut to the chase:

  * Your controllers and actions can have camelCasing to accomodate
    multiple words
  * ON THE URL, you must specify multiple words using a word separator
    ('.' or '-')
  * VIEW SCRIPTS follow the same conventions as URLs

Great -- I like and appreciate these simple guidelines.
And, more importantly, it sounds like these guidelines will stay stable for future releases of ZF.

Just to be clear, these guidelines for controller and action names are different from the simpler suggestions in the ZF docs.
The ZF docs say the default is "Title-case" (which I think really means Initial character is capitalized) for both controllers and actions: http://framework.zend.com/manual/en/zend.controller.html#zend.controller.quickstart.go.controller 
Also, Rob Allen's ZF tutorial also describes names with the Initial character as the only capitialized character and then refers to the ZF docs for more complicated naming (see tutorial v1.5.1 p 6 Setting up the Controller).

What I'm verifying in this post is that camelCase is the recommended naming convention for multiple word controller and action names, and that this is a stable recommendation going forward.