zendframework/zf2-documentation

Zend Framework 2 documentation sources

Welcome to the Zend Framework 2 documentation

End-of-Life occurred 31 March 2018

This repository mirrored Zend Framework through the 2.4 series; however, 2.4 reached its end of life on 31 March 2018.

At this time, this repository has been archived, and is read-only.

Current documentation is bundled directly in each component, and published at https://docs.zendframework.com

RELEASE INFORMATION

This documentation is based on Zend Framework 2 (master branch)

VIEW THE DOCUMENTATION ONLINE

We used the readthedocs.org project to render online the development version of the documentation of Zend Framework 2.

You can read the development online documentation in http://zf2.readthedocs.org.

You can read the last stable documentation in http://framework.zend.com/manual/current/en/index.html.

BUILDING DOCUMENTATION

Building the documentation requires Sphinx. Further requirements are Pygments, docutils and markupsafe, installable with pip install.

Descend into the docs/ directory, and run make with one of the following targets:

• epub - build epub (ebook) documentation (requires Calibre to build cross-platform epub versions)
• help - build Windows help files
• html - build HTML documentation
• info - build Unix info pages
• latexpdf - build PDF documentation (requires a working latex toolchain)
• man - build Unix manpages
• text - build ANSI text manual files

Examples:

make html

You can cleanup by running make clean.

CONTRIBUTING

If you wish to contribute to the documentation of Zend Framework 2, please read the CONTRIBUTING.md file.

If you don't know where to begin, or where you can best help, please review the TODO.md file.

LICENSE

The files in this archive are released under the Zend Framework license. You can find a copy of this license in LICENSE.txt.

ACKNOWLEDGEMENTS

The Zend Framework team would like to thank all the contributors to the Zend Framework Documentation project, our corporate sponsor, and you, the Zend Framework user. Please visit us sometime soon at http://framework.zend.com.

zf2-documentation's Issues

Usability: Fork us on Github button and navigation (lower resolution)

I know it's very trendy to have this button on every page but could You please move it somewhere else? :) On lower resolutions, or just when window is resized (my browser is scaled to ~1340px width) I'm unable to use top navigation.
For example http://framework.zend.com/manual/2.0/en/user-guide/unit-testing.html
"Modules" link is covered and I need to scroll down to get to the next chapter. On other pages links are clickable partially.

reStructuredText Style Guide

reStructuredText is a flexible markup language. There are many ways to create visually and semantically similar elements. Many different style choices were decided upon migration from the ZF1 docs. The CONTRIBUTING.MD file has a link to the reStructuredText manual, but in my opinion, it's not enough.

It would be very helpful if a Zend representitive will create a minimal style guide, simply outlining the various formatting elements that are used in the docs? This will serve mainly as a reference guide for documentation writers and fixers.

Similar in spirit to: http://alistapart.com/about/style-guide

PHP Code does not display in GitHub Docs

I really don't know if this is an error on docs, on reStructuredText, or on the way GithHub parse the rst files, but i noticed that all php codes are not being display in GitHub web interface as you can see for example in the first file of the user guide: https://github.com/zendframework/zf2-documentation/blob/master/docs/languages/en/user-guide/skeleton-application.rst

There is a php code-block in the end of the file, if you change to raw view you can see that block is in fact there, but in normal view nothing is displayed.

Missing documentation for Zend\View\Helper\Layout

The view helper "Layout" needs some explanations and examples.

https://github.com/zendframework/zf2/blob/master/library/Zend/View/Helper/Layout.php

No documentation about Session

I can not find any documentation about Session... can any one write some documentation and examples about it...?

German translation

May I ask who claims to be responsible for the german documentation?

I don't intend to be a grammar nazi, but there are a lot of spelling mistakes, missing commas and missing dashes for compound nouns.

Improve custom form element example

By actually writing a working custom form element, something like a phone number element, or a country selector element.

P.S.: This ticket is mostly just a reminder for myself, but if someone beats me to it, feel free.

ChromePHP as Zend\Log\Writer is missing

Description for "ChromePHP" as writer for Zend\Log is missing.

http://framework.zend.com/manual/2.1/en/modules/zend.log.writers.html

PHPUnit in UserGuide Number of Assertions Wrong

When reading the PHPUnit section of the user-guide I noticed the number of assertions were incorrectly listed as 2 in the example output. There is only 1 assertion when you follow the guide and run phpunit.

Missing documentation Zend\View\Helper\PaginationControl

Add the coding standards to the Reference Guide

The 1.12. has the coding standards included in the Reference Guide:
http://framework.zend.com/manual/1.12/en/coding-standard.html

The 2.x coding standards can be found in the wiki and should be added to the Reference Guide as well:
http://framework.zend.com/wiki/display/ZFDEV2/Coding+Standards

Fix service manager configuration section

Currently the documentation explains we can extend the Zend\ServiceManager\Config class & implements the configureServiceManager method to build our services.

After discuss in zendframework/zendframework#2853 , this is no longer the case. Now, instead, we can directly override the following methods to do the same thing:

• getAbstractFactories
• getAliases
• getInitializers
• getFactories
• getInvokables
• getServices
• getShared

Missing documentation for Escape view helpers

These helpers needs some explanations and examples:

• Zend\View\Helper\EscapeCss
• Zend\View\Helper\EscapeHtml
• Zend\View\Helper\EscapeHtmlAttr
• Zend\View\Helper\EscapeJs
• Zend\View\Helper\EscapeUrl

There is only a short notice in the PhpRenderer section.

Zend Cache: Overview and Theory Of Operation with examples would help

I have started diving into the Zend\Cache component and I notice that it takes me more time to puzzle together how to work with the component compared to when having overview documentation.

The existing pieces of documentation are too technical an assume a basic understanding of the component. For example the first line of patterns: Cache patterns are configurable objects to solve known performance bottlenecks; I need read the rest of the document to determine the intention of this line.

A separate Overview of Theory Of Operation providing a bird's eye view of the component might help to provide insight in the system as a whole and how it works.

if I can spare some time I will try to write a chapter but at this moment I cannot promise anything due to time constraints

Add milestones and labels to issues

Please define milestones and add them to issues. Also add labels.

Registering module-specific listeners explanation is not complete.

I think the example :

namespace SomeCustomModule;

class Module
{
    public function onBootstrap($e)
    {
        $application = $e->getApplication();
        $config      = $application->getConfiguration();
        $view        = $application->getServiceManager()->get('View');
        $view->headTitle($config['view']['base_title']);

        $listeners   = new Listeners\ViewListener();
        $listeners->setView($view);
        $application->getEventManager()->attachAggregate($listeners);
    }
}

explanation is not complete in modules/zend.mvc.examples.rst

PHPUnit in UserGuide Number of Assertions Wrong in Routing and Controllers

The number of tests and assertions are incorrect.

Advanced use of forms shows code that doesn't work and is confusing

Attempting to follow the advanced use of forms to create custom elements but the examples provided don't work.

• "Then, you can use your custom element like any other elements:" says you can use your custom element like other elements but uses $form->add when I've only seen examples for adding elements directly within the class up until here by doing $this->add. Doing $this->add() gives a servicemanager error: "was unable to fetch or create an instance for Custom". In fact there's code that does exactly that by adding the custom element within __construct().

Missing documentation for Zend\Validator\Csrf

Csrf is not listed as a standard validator class.

Missing Rackspace API Setup Documentation

There's a page that explains how to use the Rackspace API (http://framework.zend.com/manual/2.1/en/modules/zendservice.rackspace.html) but there isn't any documentation on how to set it up or how to get that and other services working.

No documentation about options of Zend\Json\Json

There is no documentation about the options argument of Zend\Json\Json::encode

Unit tests in the tutorial

Hello.

I've noticed last night that there is a section, or, rather sections, about unit testing in the ZF2 tutorial. This is indeed awesome, but! Seems to me that the unit tests are trying to be TDD-ish, but will instead just confuse newcomers trying to learn ZF2. Several reasons.

• The Unit Testing section is the first http://zf2.readthedocs.org/en/latest/user-guide/unit-testing.html. The problem with this being first is that it speaks about modules, ViewModels, and other things that the developer knows nothing about (yet).
• It uses PHPUnit 3.5.15 as shown in the example outputs, but this should be the PHPUnit version we use to actually test ZF2 itself (which is 3.6.x I think).
• The next problem can be seen on the Routing and controllers section http://zf2.readthedocs.org/en/latest/user-guide/routing-and-controllers.html. The code itself are just 4 empty actions (index, add, edit, delete), but the tests are testing these 4 actions that they return a ViewModel, about which the developer still doesn't know anything about. And these tests PASS where it's obvious that they should fail.

This 3rd problem is the biggest one as this will confuse new developers the most: "How come my tests fail when they pass in the tutorial? What am I doing wrong?! ARGH!!"

I really do welcome these unit test examples in the tutorial, but I feel they should be either full-blown TDD tests, covering everything (including unit tests with mocks for TableGateways and Forms), first shown how they fail and then we fix and then they pass, or the entire Unit Testing section should be moved last (that is, before the Conclusion section), and everything about unit testing should be here, and here only.

I, personally, vote for the latter - a Unit testing section at the end. Why? Because the developer came to learn about ZF2, and intermixed tests all over the place would just create confusion and would make things more difficult for newcomers.

Thoughts?

Where's the Coding Standard?

I wanted to send the link to a fellow developer and could only find the coding standards for 1.12.

Error in an example in Zend\Mvc > Introduction to the MVC Layer

The code in the example of the part "Bootstrapping an Application"

$config = include 'config/application.config.php';
$serviceManager = new ServiceManager();
...
$serviceManager->setService('ModuleManager', new ModuleManager());

is incorrect. The first argument for new ModuleManager() is missing:

Warning: Missing argument 1 for Zend\ModuleManager\ModuleManager::__construct()

I guess the $config should be passed:

$serviceManager->setService('ModuleManager', new ModuleManager($config));

Explain how elements can be added to a form

Currently, forms are explained with the ZendSkeletonApplication.

There, form elements are added to the form by using

$this->add(array(
    'name' => 'artist',
    'attributes' => array(
        'type'  => 'text',
    ),
    'options' => array(
        'label' => 'Artist',
    ),
));

Please explain why elements are added this way and not be adding concrete instances of Zend\Form\Element\Element. Please explain the alternatives available.

Wrong indications unit-testing.rst

In Bootstrapping your tests there is a reference to a zf-tutorial/tests/ never mentioned before.

Maybe it should be zf2-tutorial/module/Application/test, but in that case the init_autoloader.php path is wrong.

No content on the Zend\File\ClassFileLocator page

http://zf2.readthedocs.org/en/latest/modules/zend.file.class-file-locator.html

Review and update TODO list

The TODO list needs a review and a update.

https://github.com/zendframework/zf2-documentation/blob/master/TODO.md

Add PhpDoc-comments to code examples in the documentation

Currently, in the code examples in the documentation, PhpDoc-comments for class methods are missing. While I believe adding them doesn't do any harm, I'm convinced that these would greatly improve the documentation, as well as convey good craftsmanship.

Better Explanation (With Examples) in Zend\Navigation\Page\Mvc Docs

There is a table in Zend\Navigation\Page\Mvc Section of the docs that list the parameters you can use to add a page to Navigation component, but there is no example that show how to use "routeMatch" and "Router" params. in fact the description doesn't tell much about the use the params itself, so it will be very insteresing if anyone add some information about it.

Thanks

Missing documentation for Zend\View\Helper\FlashMessenger

The view helper "FlashMessenger" needs some explanations and examples.

In the forms section, set the action attribute in the controller action, not in the view

Currently, at

• https://github.com/zendframework/zf2-documentation/blob/master/docs/languages/en/user-guide/forms-and-actions.rst

the action attribute of the form is set in the view. Shouldn't it rather be set in the controller action?

package documentation available but not browsable

All the zend packages that live in the '\Zend*' namespace do have documentation but aren't indexed...

example
https://zf2.readthedocs.org/en/latest/modules/zendqueue.introduction.html
or
https://zf2.readthedocs.org/en/latest/modules/zendpdf.introduction.html

you can not browser there unless you know the url or search for it.

Provide an alternative to the ZendSkeletonApplication

While the ZendSkeletonApplication may provide an end user with a working application, it doesn't explain the rationale behind components used therein.

An end user should be able to create an application from scratch, by only using the documentation, rather than from an example application. The documentation should not only explain how to use components of the framework, but why they exist in the first place. This is especially important for the components that have not been available in ZF1.

Further explain tests, especially test setup (at best with PhpDoc or inline comments)

While I understand that the ZF2 documentation should not be the place to teach developers about

• what unit testing is
• why it should be done and
• when it should be done

although I see some disparity between the online classes that are given where one will be given a TDD approach and the documentation, where tests are written after the code to be tested) - I believe the documentation should point out in the test examles, why they are laid out the way they are. For example, why are the setup() methods designed the way they are?

This could be achieved with PhpDoc or inline comments in the actual examples (which would not require a reader to jump back and forth between examples and surrounding, explanative text.

See #478.

[Userguide] Changing order

To me, it looks like there is a bug in the order of the User-guide articles. After an introduction to the tutorials (article 1), there is an article about installing Zend Skeleton (article 2) and then we go straight to a Unit Test article.

I know TDD is one of the best approces on creating a webpage, but testing a 'controller' or 'module' without knowing what those are is a little confusing. I suggest using this order:

1. Getting Started with Zend Framework 2
2. Getting started: A skeleton application
3. Modules
4. Routing and controllers
5. Database and models
6. Unit Testing
7. Styling and Translations
8. Forms and actions
9. Conclusion

Form elements are missing (DateSelect and DateTimeSelect)

• Zend\Form\Element\DateSelect
• Zend\Form\Element\DateTimeSelect

Performance section

Hello,

in ZF1 there was a performance section, with tips how to improve the performance of the whole framework or components.
http://framework.zend.com/manual/1.12/en/performance.html

This would be also fine for ZF2

PHP Assist

Hi guys,
I had a thought about integrate PHP Assist into zf2 documentation so users will have the ability to see a live demo of the code displayed in the docs and option to play with it and see how things working.

Does it sound interesting ?

you may wanna check how PHP Assist works and what it have to offer: http://www.youtube.com/watch?v=u-Jz9y-aBRc

btw, one thing that isn't shown on the video is that it have javascript api that allow to convert the code found on the page automatically to active widget, this way the source code is always available in the docs server but in runtime it converted to widget.

Skeleton Application installation procedure is broken

In http://framework.zend.com/manual/2.1/en/user-guide/skeleton-application.html, the command tries to install the application via download from some URL inaccessible without a GitHub account (possibly GitHub issue itself):

php composer.phar create-project --repository-url="http://packages.zendframework.com" zendframework/skeleton-application path/to/install

Output looks like following:

Marco@WS-64 /c/Users/Marco/Documents/vhosts/comcom-cms.localhost/application/tst (master)
$ php composer.phar create-project --repository-url="http://packages.zendframework.c
om" zendframework/skeleton-application tst2
Installing zendframework/skeleton-application (2.1.0)
  - Installing zendframework/skeleton-application (2.1.0)
    Downloading: connection...
Could not fetch https://api.github.com/repos/zendframework/ZendSkeletonApplication/zipball/zf/release-2.1.0, enter your GitHub credentials to access p
rivate repos
The credentials will be swapped for an OAuth token stored in C:\Users\Marco\AppData\Roaming/Composer/config.json, your password will not be stored
To revoke access to this token you can visit https://github.com/settings/applications
Username:

fix/user-guide/modules

The Note about the psr-0 autoloader alternative are worded confusingly and also seem to be wrong.

I think it should say to set Album (not Application). This should be added to composer.json:

"autoload": {
    "psr-0": { "Album": "module/Album/src/" }
},

and run composer update.

Then make sure you still have declared:

public function getAutoloaderConfig() { }

in Module.php or it won't work

Caching Documentation Incorrect

If you look at the examples at the bottom of this page the code is incorrect and causes exceptions to be thrown.

http://zf2.readthedocs.org/en/latest/modules/zend.cache.storage.adapter.html

Rebuilding docs in develop branch is slow

When rebuilding the develop branch, it doesn't seem to be detecting unchanged source files the same way as the master branch is:

# Fresh clone of zf2-documentation...

Switched to branch 'master'
➜  zf2-documentation/docs git:(master) % rm -rf tmp    
➜  zf2-documentation/docs git:(master) % make html LANG=en          # 1st build (master)
# No changes... just re-build right away
➜  zf2-documentation/docs git:(master) % time make html LANG=en     # 2nd build (master)
sphinx-build -b html -d _build/doctrees   tmp/en _build/html
Running Sphinx v1.1.3
loading translations [en]... locale not available
loading pickled environment... done
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 3 changed, 0 removed
...
make html LANG=en  6.35s user 0.37s system 93% cpu 7.209 total

➜  zf2-documentation/docs git:(master) % git checkout develop
Switched to branch 'develop'
➜  zf2-documentation/docs git:(develop) % rm -rf tmp    
➜  zf2-documentation/docs git:(develop) % make html LANG=en         # 1st build (develop)
# No changes... just re-build right away
➜  zf2-documentation/docs git:(develop) % time make html LANG=en    # 2st build (develop)
sphinx-build -b html -d _build/doctrees   tmp/en _build/html
Running Sphinx v1.1.3
loading translations [en]... locale not available
loading pickled environment... done
building [html]: targets for 530 source files that are out of date
updating environment: 0 added, 530 changed, 0 removed
...
make html LANG=en  95.95s user 1.75s system 99% cpu 1:38.33 total

Zend\Validate\Alpha is documented but non existing in the library

See http://framework.zend.com/manual/2.1/en/modules/zend.validator.set.html#alpha

When you try to run the code there it throws a error
PHP Fatal error: Class 'Zend\Validator\Alpha' not found in

apparently the alpha validator is located in \Zend\I18n\Validator\Alpha

Missing documentation for Zend\View\Helper\Gravatar

The view helper "Gravatar" needs some explanations and examples.

https://github.com/zendframework/zf2/blob/master/library/Zend/View/Helper/Gravatar.php

TBD. at Learning Dependency Injection page

at "Very brief introduction to Di Container." still look "TBD.", so it should be removed ?

“Learning Dependency Injection” tutorial update

The "Learning Dependency Injection" tutorial should be reviewed and updated, since it references nonexistent classes/methods.

Chapter "Simplest Usage Case Without Type-hints": class AggregateDefinition

Chapter "Simplest usage case (2 classes, one consumes the other)": method getInstanceManager()

Replace references to `Zend_` classes

In the documentation, I found a lot of references to Zend_ classes, which I guess originate in the documentation adapted from ZF1. Is this true?

I guess this stuff should be fixed.

There are a number of references to Zend_, that is, 5594.

Missing documentation for Zend\Stdlib

The Zend\Stdlib component should be explained (like What is it and why does it exists).
Furthermore the components contains some very helpful classes that should be explained, too.

List of classes definitely needs a documentation:

• Zend\Stdlib\ArrayUtils
• Zend\Stdlib\StringUtils / Zend\Stdlib\StringWrapper\*
• Zend\Stdlib\ErrorHandler
• Zend\Stdlib\Glob
• Zend\Stdlib\Hydrator\* (documentation exist)

List of classes eventually needs a documentation:

• Zend\Stdlib\AbstractOptions
• Zend\Stdlib\Message
• Zend\Stdlib\Parameters
• Zend\Stdlib\Request
• Zend\Stdlib\Response
• Zend\Stdlib\DateTime
• Zend\Stdlib\ArrayStack
• Zend\Stdlib\ArrayObject
• Zend\Stdlib\PriorityQueue
• Zend\Stdlib\Spl*

Obey PSR-2 in code examples in documentation

While it could be regarded as nitpicking, I believe it would convey great craftsmanship as well if code examples in the documentation followed PSR-2, which, as far as I know, ZF2 has adopted.