Add better documentation for the deployment.properties properties

[slaff]

• Explain what is appdir directory and what is scriptsdir.
• Give examples how the appdir is working and how to include and exclude files.
• Give examples how the scriptsdir is working and how to include and exclude files.
• Add the final information to a wiki and append it to the existing Zend Server documentation.

[slaff]

In the deployment.xml one can specify a directory where the scripts will be stored. This directory will be generated in the ZPK only.

The following xml instructs the packaging tool to create, in the ZPK only, a new directory called scripts and put the script files there.

<?xml version="1.0" encoding="UTF-8"?>
<package xmlns="http://www.zend.com/server/deployment-descriptor/1.0" version="2.0">
...
    <scriptsdir>scripts</scriptsdir>
...
</package>

Using a declaration like the one below

<?xml version="1.0" encoding="UTF-8"?>
<package xmlns="http://www.zend.com/server/deployment-descriptor/1.0" version="2.0">
...
    <scriptsdir>scripts/zend-server-deployment</scriptsdir>
...
</package>

Will create in the ZPK a new directory called scripts/zend-server-deployment .

If you set an empty value for the scripts directory then there will be no scripts added to the ZPK!

<?xml version="1.0" encoding="UTF-8"?>
<package xmlns="http://www.zend.com/server/deployment-descriptor/1.0" version="2.0">
...
    <scriptsdir></scriptsdir>
...
</package>

[slaff]

We have the following results from testing with the latest version of Zend Studio.

In the deployment.properties file the scriptsdir.includes propery is used to specify which folders or files will be included in the ZPK as scripts. The value of this property is comma separated list of paths. The paths can be files or directories.

PHP files that are matching the following pattern pre_[stage|activate|deactivate|unstage|rollback].php or post_[stage|activate|deactivate|unstage|rollback].php and in the root of the scripts directory will be executed from Zend Server.

Let's say we have scripts as a scriptsdir value defined in the deployment.xml and a project with the following structure:

configs/     
modules/
     Application/
          ...
          scripts/
               pre_stage.php
               post_stage.php
public/
     css/
         layout.css
     index.php
utils/
    deployment-scripts/
          pre_stage.php
          post_stage.php
deployment.xml
deployment.properties

Adding files to the list

The following definition in the deployment.properties
scriptsdir.includes = utils/deployment-scripts/pre_stage.php
will result in the following directories and files

scripts/
           pre_stage.php

Notice that if you specify a file then the directory structure is gone. Pre_stage.php will be executed in Zend Server.

The following definition in the deployment.properties
scriptsdir.includes =utils/deployment-scripts/pre_stage.php, utils/deployment-scripts/post_stage.php
will result in the following directories and files

scripts/
           pre_stage.php
           post_stage.php

Pre_stage.php and post_stage will be executed in Zend Server.

Adding directories to the list

The following definition in the deployment.properties
scriptsdir.includes = utils/
will result in the following directories and files

scripts/
       pre_stage.php
       post_stage.php

As with the files the directory structure will be removed and only the files will be added. Pre_stage.php and post_stage will be executed in Zend Server.

_Warning_: this is valid if only one directory is specified. Adding a second directory or file will result in different directory structure in the ZPK.

The following definition in the deployment.properties
scriptsdir.includes = utils/, utils/deployment-scripts/
will result in the following directories and files

scripts/
       utils/
              deployment-scripts/
                     pre_stage.php
                     post_stage.php           
       deployment-scripts/
              pre_stage.php
              post_stage.php           

_Warning_: None of the pre_stage or post_stage PHP files will be executed in Zend Server! The reason for this is that they are not in the root of the scripts directory.

Mixing files and directories is possible.
The following definition in the deployment.properties
scriptsdir.includes = utils/,utils/deployment-scripts/pre_stage.php
will result in the following directories and files

scripts/
       utils/
              deployment-scripts/
                     pre_stage.php
                     post_stage.php           
      pre_stage.php

Only the pre_stage.php in the root scripts directory will be executed in Zend Server!

[boedah]

@slaff: thanks for specifying.

Stripping any directory seems rather strange to me, as I want to preserve the structure therein (maybe I want to include helper libraries etc.).

This should definitely be included in the official Zend Server documentation, e.g. http://files.zend.com/help/Zend-Server/content/preparing_the_package_using_the_deployment_tool.htm

Also there is no mention of this ZendServerSDK (instead zdpack), which is (correct me, if I am wrong) the new official way to pack a ZPK.

[ryanheath86]

@slaff Amazing detail, thanks! I wasn't aware that adding multiple directories had that effect, and as such my fix will not account for this. To me that part seems a bit backwards; if you add one directory, it get's flattened, along with all it's sub directories, if you add more than one, none of them do!

@boedah To answer your question (as it is exactly what I would like to do), it would appear, though I haven't tested, that you could have

script-sources/
    /resources
        functions.php
        includes.inc
    post_stage.php
    pre_stage.php

.. and use...

scriptsdir.includes=script-sources/resources,script-sources/post_stage.php,script-sources/pre_stage.php

As it is, I just add the script-sources folder and that puts everything flat in the scripts directory, after all, it's in the package, so I don't care that it looks a little messy.