Table of Contents
Intro
ZendServerSDK, aka zs-client, is a command line application that communicates with
Zend Server's WebAPI. It can run on all modern Operating Systems(OS) such
as Linux, Mac OS X and Windows., (*1)
Requirements
PHP version >=5.3.3 with enabled phar module., (*2)
Installation
You can copy locally the latest stable version as a stand-alone file from:
https://github.com/zend-patterns/ZendServerSDK/raw/master/bin/zs-client.phar, (*3)
On Linux you can execute the following command:, (*4)
wget https://github.com/zend-patterns/ZendServerSDK/raw/master/bin/zs-client.phar
Contributing
Linux: 
and Windows: 
, (*5)
If you wish to contribute to the project, please read the CONTRIBUTING.md, (*6)
Usage
Run the phar file with --help to see the available commands:, (*7)
php zs-client.phar --help
Use Cases
Adding Target
A target is representing the information needed to connect to a Zend Server.
Every target contains unique name and must have URL that points to
the location of the Zend Server, WebAPI key and secret and optionally a target
can contain information about the version of Zend Server., (*8)
To add a target run the following command:, (*9)
php bin/zs-client.phar addTarget --target="<put-here-unique-name>" \
--zskey="<put-here-the-webapi-key-name>" \
--zssecret="<put-here-the-webapi-key-hash>" \
--zsurl="<(optional)put-here-valid-url>" \
--zsversion="<(optional)put-here-the-version>"
To update a target run the command with the same --target value and provide the
new values., (*10)
zsurl: if not specified, the value http://localhost:10081 is used.
zsversion: if not specified, the latest Zend Server version will be used., (*11)
The information about the available targets is saved in the home directory of
the current user in a file named .zsapi.ini., (*12)
Using Targets
Once a target has been defined, specify it in subsequent commands by adding
its unique name to the argument list, as in this example:, (*13)
php bin/zs-client.phar monitorGetIssuesListPredefinedFilter \
--target="<unique-name-from-addTarget-command>" \
--filterId="Resources Issues"
Deploying PHP application
You have a PHP application that you want to deploy to Zend Server.
In order to use the deployment you will have to enable deployment support,
create a package and upload it to the remote server., (*14)
Below are the steps that you need to take:, (*15)
Enable Deployment Support
php bin/zs-client.phar initZpk --folder="<folder-where-the-PHP-code-is>"
This will add two new files in the specified folder: deployment.xml and deployment.properties., (*16)
Using Zend Studio 10 or normal text editor edit the deployment.xml file and change
the XML data to match your application name, version, etc., (*17)
Create Package
Run the following command., (*18)
php bin/zs-client.phar packZpk --folder="<folder-where-the-PHP-code-is>" --destination="<folder-where-the-package-will-be-created>"
It will output the name of the newly created package file. You have to use this name to install
or update an existing application on Zend Server. If you want to use other name for
the output file you can use the --name="{desired-zpk-name}" option., (*19)
Composer Integration
There is experimental integration with composer that allows you to download the dependant packages, as described in composer.json,
download them and convert them to zpk files. The above command with composer integration will look like this, (*20)
php bin/zs-client.phar packZpk --folder="<folder-where-the-PHP-code-is>" \
--destination="<folder-where-the-package-will-be-created>" \
--composer
The result from the command will be list of packages in the order that they have to be installed (top first, bottom last).
Example:, (*21)
/tmp/zendframework.zend-stdlib-2.2.4.zpk
/tmp/zendframework.zend-console-2.2.4.zpk
/tmp/zendframework.zend-file-2.2.4.zpk
/tmp/zendframework.zend-mvc-2.2.4.zpk
/tmp/zendframework.zend-text-2.2.4.zpk
/tmp/zendframework.zend-math-2.2.4.zpk
/tmp/zendframework.zend-json-2.2.4.zpk
/tmp/zendframework.zend-serializer-2.2.4.zpk
/tmp/zenddevops.webapi-dev-dev.zpk
/tmp/AddYourUniqueApplicationName-1.0.0.zpk, (*22)
Deploy Package
Run the following command to install a package., (*23)
php bin/zs-client.phar installApp --zpk="<location-of-the-zpk-file>" \
--target="<the-name-of-the-target>" \
--baseUri="<baseUri>"
You can use the same command to update a package. User parameters during the
installation can be passed using --userParams="{provide-params-as-query-string}".
For example if you want to pass parameter APPLICATION_ENV and DB_TYPE then you can
use the following, (*24)
php bin/zs-client.phar installApp --zpk="<location-of-the-zpk-file>" \
--target="<the-name-of-the-target>" \
--baseUri="<baseUri>" \
--userParams="APPLICATION_ENV=staging&DB_TYPE=mysql"
Safe Package Deployment
If you deploy a new version of your zpk if the old version is still being deployed then
this can lead to unpredictable results. In order to prevent this you can use the --safe flag.
If it is present zs-client will check if there is a current deployment going on for this app
and will exit if that is the case., (*25)
Example:, (*26)
php bin/zs-client.phar installApp --zpk="<location-of-the-zpk-file>" --safe ...
If you want to be safe AND want to wait for the previous deployment to finish then
you can use the --safe and --wait flags together., (*27)
Example:, (*28)
php bin/zs-client.phar installApp --zpk="<location-of-the-zpk-file>" --safe --wait ...
Deploy Multiple Packages
If you use the composer integration then packZpk can create multiple packages, instead of one. Below is a suggestion how you can
deploy these newly created packages in the correct order., (*29)
ZPKS=`php bin/zs-client.phar packZpk --folder="<folder-where-the-PHP-code-is>" \
--destination="<folder-where-the-package-will-be-created>" \
--composer`;
for i in $ZPKS; do
php bin/zs-client.phar installApp --zpk="$i" \
--target="<the-name-of-the-target>" \
--baseUri="<baseUri>" \
--userParams="APPLICATION_ENV=staging&DB_TYPE=mysql"
done;
HTTP tuning
Changing Connection Timeout
In some cases we may expect slower communication between the client and the server.
In that case we can set explicitly the http timeout to a bigger value. The example below shows how to set it to 40 seconds., (*30)
php bin/zs-client.phar getSystemInfo --target="<name-of-the-target> \
--http="timeout=40"
Accepting Self-Signed SSL Certificates
In most cases the HTTPS access to your Zend Server will use self-signed certificate.
In order to instruct the client to accept the SSL certificate you can do the following., (*31)
php bin/zs-client.phar getSystemInfo --target="<name-of-the-target> \
--http="sslverify=0"
Combining Multiple HTTP options
If you want to combine multiple HTTP options in the same request then you can format the value of the http parameter as a valid
HTTP query string. Request with timeout of 40 seconds and acceptance of self-signed certificates will look like this., (*32)
php bin/zs-client.phar getSystemInfo --target="<name-of-the-target> \
--http="timeout=40&sslverify=0"
Persisting the HTTP Options
If you want to keep the http options saved to a target then when defining or updating the target define also the http parameter.
Format the value as valid HTTP query string. Take a look at the following example., (*33)
php bin/zs-client.phar addTarget --target="<name-of-the-target> \
--zsurl="http://x.y.z" \
--zskey="admin" \
--zssecret="<secret-hash>" \
--http="timeout=40&sslverify=0"
In the cases where the output is text zs-client supports three formats: xml, which is the default one,
json and kv(key value). To specify the desired format you have to use the --output-format parameter., (*34)
Example:, (*35)
php bin/zs-client.phar getSystemInfo --target=zserver --output-format=kv
Will return, (*36)
status=Error
edition=ZendServerCluster
zendServerVersion=7.0.0
supportedApiVersions[0]=application/vnd.zend.serverapi;version=1.2
supportedApiVersions[1]=application/vnd.zend.serverapi;version=1.3
...
supportedApiVersions[6]=application/vnd.zend.serverapi;version=1.8
phpVersion=5.5.13
operatingSystem=Linux
deploymentVersion=2.0
serverLicenseInfo[status]=OK
...
serverLicenseInfo[nodeLimit]=100
serverLicenseInfo[edition]=ENTERPRISE
...
managerLicenseInfo[evaluation]=
````
Providing array values
======================
Some commands accept arrays as arguments.
For example configurationExtensionsOn allows you turn on multiple extensions at
the same time. The code below turns on bcmath and tidy:
php bin/zs-client.phar configurationExtensionsOn --target=zserver --extensions=bcmath,tidy, (*37)
Notice the syntax of the extensions value. It is a list of items having comma as delimiter.
If for some reason you want to replace the comma with another delimiter this can be done by
adding the new delimiter enclosed in smaller than (<) and bigger than (>).
In the example below we use semicolon as delimiter:
php bin/zs-client.phar configurationExtensionsOn --target=zserver --extensions=bcmath;tidy;, (*38)
If needed you can pass more complicated array data. For example a PHP array like the one below ...
```php
$data = array (
'x' => array(
'a' => 1,
'b' => 2,
),
y => 3
);
... can be represented in the command line using the following syntax., (*39)
php bin/zs-client.phar installApp --userParams='x[a]=1&x[b]=2&y=3' --target=zserver ...
Here the default delimiter is &. If you want to use custom delimiter,
semicolon for example, then you can specify it similar to the previous example:, (*40)
php bin/zs-client.phar installApp --userParams='x[a]=1;x[b]=2;y=3<;>' --target=zserver ...
Notice about delimiters: Choose your delimiter wisely.
* Choose custom delimiter only if the default ones ("," and "&") do not work for you.
* A delimiter should not be special character that is interpreted by your shell.
* A delimiter should not be special character that is removed silently by your shell.
* A delimiter should not be one of the characters that are already in the data., (*41)
Deployment properties syntax
In the deployment.properties file one can specify the files that will become part of the
application or part of the deployment scripts.
Read this document for more information.
Make sure to read about the way scriptsdir.includes values are processed., (*42)
For application excludes we support following wildcard syntax:, (*43)
-
**/{something} - will exclude all entries that have base name {something},
no matter if they are files or folders,
Example: **/.svn excludes all folders and files with the name .svn. This is true
for /.svn, public/.svn or module/folder-with-file/.svn.
If the entry is folder then the content of that folder and sub-folders will be excluded too.
-
*{something} - will exclude all entries ending with {something} in their name.
Example: *.fla will exclude all files ending with .fla, like video.fla.
or directories, like more.fla.
Feedback
For questions and feedback write to slavey (at) zend DOT com., (*44)
Wallogit.com
