You are viewing a plain text version of this content. The canonical link for it is here.
Posted to zeta-commits@incubator.apache.org by to...@apache.org on 2010/11/06 18:01:33 UTC
[zeta-commits] svn commit: r1032125 - in /incubator/zetacomponents/website/htdocs:
community/implementation.html community/implementation.txt
documentation/install.html documentation/install.txt
Author: toby
Date: Sat Nov 6 18:01:32 2010
New Revision: 1032125
URL: http://svn.apache.org/viewvc?rev=1032125&view=rev
Log:
- Updated: Re-generated website HTML to incorporate latest changes.
Modified:
incubator/zetacomponents/website/htdocs/community/implementation.html
incubator/zetacomponents/website/htdocs/community/implementation.txt
incubator/zetacomponents/website/htdocs/documentation/install.html
incubator/zetacomponents/website/htdocs/documentation/install.txt
Modified: incubator/zetacomponents/website/htdocs/community/implementation.html
URL: http://svn.apache.org/viewvc/incubator/zetacomponents/website/htdocs/community/implementation.html?rev=1032125&r1=1032124&r2=1032125&view=diff
==============================================================================
--- incubator/zetacomponents/website/htdocs/community/implementation.html (original)
+++ incubator/zetacomponents/website/htdocs/community/implementation.html Sat Nov 6 18:01:32 2010
@@ -10,15 +10,15 @@
<meta name="description" content="Apache Zeta Components - reusable set of high quality PHP components to fasten your development." />
<meta name="keywords" content="PHP, apache, components, framework, quality" />
- <meta name="author" content="Kore Nordmann" />
+ <meta name="author" content="Tobias Schlitt" />
<meta name="language" content="en" />
- <meta name="date" content="Tue, 03 Aug 2010 10:23:50 +0200" />
+ <meta name="date" content="Sat, 06 Nov 2010 14:14:34 +0100" />
<meta name="robots" content="all" />
<link rel="schema.DC" href="http://purl.org/dc/elements/1.1/" />
<meta name="DC.title" content="Guidelines" />
- <meta name="DC.creator" content="Kore Nordmann" />
- <meta name="DC.date" content="Tue, 03 Aug 2010 10:23:50 +0200" />
+ <meta name="DC.creator" content="Tobias Schlitt" />
+ <meta name="DC.date" content="Sat, 06 Nov 2010 14:14:34 +0100" />
<meta name="DC.rights" content="Copyright" />
<link rel="meta" href="/zetacomponents/community/implementation.rdf" />
@@ -372,10 +372,26 @@ class ezcFooBar
/**
* File containing the ezcFooBar class
*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ *
* @package Mail
* @version //autogen//
- * @copyright Copyright (C) 2005-2007 eZ systems as. All rights reserved.
- * @license http://ez.no/licenses/new_bsd New BSD License
+ * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
*/
/**
@@ -486,13 +502,29 @@ public function __construct( $email, $na
}</code><p>A __set_state() method is not required, but recommended. The __set_state() method can be used to create an object of this class from a serialized PHP variable. The method's implementation looks like:</p><code class="block">static public function __set_state( array $array )
{
return new ezcMailAddress( $array['email'], $array['name'] );
-}</code><p>See also <a href="#documenting-set-state">Documenting __set_state</a> on how to document this method.</p><a name="dealing-with-files"></a><a name="id32"></a><h3>Dealing with Files</h3><a name="reading-files"></a><a name="id33"></a><h4>Reading files</h4><p>If possible try to use some of the PHP functions for reading in files, eg. file(), instead of having custom PHP code.</p><p>Avoid reading in whole files in memory if this is not needed. In this cases you should not use file() and the likes. Instead read a chunk of the file into a buffer (e.g. 4096 bytes) and work on that.</p><a name="writing-files"></a><a name="id34"></a><h4>Writing files</h4><p>When writing to files never assume that only one process will access the same file at the same time. This means you should create code that does either (or both):</p><ul><li><p>File locking, lock the file for reading until the writing is finished, this avoids other processes reading half-finished files.</p></li><li><p>Te
mporary files, create a new file which is used for writing (locking might be a good idea too). When the file writing is done the original file is backed up (renamed/moved) and the new one copied/moved as the original. (A caveat: using tail -f will not work).</p></li></ul><a name="unicode-and-utf-8"></a><a name="id35"></a><h3>Unicode and UTF-8</h3><p>All components internally should handle UTF-8, and where possible parsers should always return UTF-8 as well.</p><a name="unicode-caveats"></a><a name="id36"></a><h4>Unicode caveats</h4><p>Case handling in PHP 6 will differ from earlier because it uses the current locale when doing the operation. This means that in some locales you can have non-revertible case changes.</p><p>There is no workaround for this at the moment other than checking for the original string and the lowercase string at the same time or using only lowercase characters at all times.</p><a name="id2"></a><a name="id37"></a><h3>Documentation</h3><p>This docume
nt explains how PHP source and source files should be documented in order to meet the required standards for documentation.</p><p>All PHP source should be documented using phpDocumentor syntax. The rest of this document is concerned with:</p><ul><li><p>Source that is required to be documented.</p></li><li><p>The tags that are required to be used in the various contexts.</p></li><li><p>Optional documentation.</p></li><li><p>Wording rules.</p></li></ul><p>In general the examples show in what order the various tags should be used.</p><a name="file-documentation"></a><a name="id38"></a><h4>File documentation</h4><p>Required in all source files with and without a class. PHPDocumentor will show a warning message otherwise.</p><p>The following fields are required:</p><ul><li><p>A short (one line) description of the file.</p></li><li><p>@version</p></li><li><p>@package</p></li><li><p>@copyright</p></li><li><p>@license</p></li></ul><p>The following fields are optional:</p><ul><li><p>
a longer description of the file if the short description does not suffice. Only needed when the file doesn't contain one class.</p></li><li><p>@subpackage Tests To be used for files/classes that make out a part of the test suite.</p></li></ul><p>Example:</p><code class="block">/**
+}</code><p>See also <a href="#documenting-set-state">Documenting __set_state</a> on how to document this method.</p><a name="dealing-with-files"></a><a name="id32"></a><h3>Dealing with Files</h3><a name="reading-files"></a><a name="id33"></a><h4>Reading files</h4><p>If possible try to use some of the PHP functions for reading in files, eg. file(), instead of having custom PHP code.</p><p>Avoid reading in whole files in memory if this is not needed. In this cases you should not use file() and the likes. Instead read a chunk of the file into a buffer (e.g. 4096 bytes) and work on that.</p><a name="writing-files"></a><a name="id34"></a><h4>Writing files</h4><p>When writing to files never assume that only one process will access the same file at the same time. This means you should create code that does either (or both):</p><ul><li><p>File locking, lock the file for reading until the writing is finished, this avoids other processes reading half-finished files.</p></li><li><p>Te
mporary files, create a new file which is used for writing (locking might be a good idea too). When the file writing is done the original file is backed up (renamed/moved) and the new one copied/moved as the original. (A caveat: using tail -f will not work).</p></li></ul><a name="unicode-and-utf-8"></a><a name="id35"></a><h3>Unicode and UTF-8</h3><p>All components internally should handle UTF-8, and where possible parsers should always return UTF-8 as well.</p><a name="unicode-caveats"></a><a name="id36"></a><h4>Unicode caveats</h4><p>Case handling in PHP 6 will differ from earlier because it uses the current locale when doing the operation. This means that in some locales you can have non-revertible case changes.</p><p>There is no workaround for this at the moment other than checking for the original string and the lowercase string at the same time or using only lowercase characters at all times.</p><a name="id2"></a><a name="id37"></a><h3>Documentation</h3><p>This docume
nt explains how PHP source and source files should be documented in order to meet the required standards for documentation.</p><p>All PHP source should be documented using phpDocumentor syntax. The rest of this document is concerned with:</p><ul><li><p>Source that is required to be documented.</p></li><li><p>The tags that are required to be used in the various contexts.</p></li><li><p>Optional documentation.</p></li><li><p>Wording rules.</p></li></ul><p>In general the examples show in what order the various tags should be used.</p><a name="file-documentation"></a><a name="id38"></a><h4>File documentation</h4><p>Required in all source files with and without a class. PHPDocumentor will show a warning message otherwise. In addition, the license information must be available in <strong>all files</strong>.</p><p>The following fields are required:</p><ul><li><p>A short (one line) description of the file.</p></li><li><p>@version</p></li><li><p>@package</p></li><li><p>@license</p></
li></ul><p>The following fields are optional:</p><ul><li><p>a longer description of the file if the short description does not suffice. Only needed when the file doesn't contain one class.</p></li><li><p>@subpackage Tests To be used for files/classes that make out a part of the test suite.</p></li></ul><p>The following fields may not occur:</p><ul><li><p>@copyright</p></li></ul><p>Example:</p><code class="block">/**
* Short description of the contents of the file.
*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ *
* @version //autogen//
* @package PackageName
- * @copyright Copyright (C) 2005-2007 eZ systems as. All rights reserved.
- * @license http://ez.no/licenses/new_bsd New BSD License
+ * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
*/</code><a name="class-documentation"></a><a name="id39"></a><h4>Class documentation</h4><p>Required for all classes.</p><p>The following fields are required:</p><ul><li><p>A brief one line description of the class.</p></li><li><p>An extensive description of the class. Use examples unless it is obvious how to use the class.</p></li><li><p>@package</p></li><li><p>@version</p></li></ul><p>The following fields are optional:</p><ul><li><p>@tutorial, if there are relevant tutorials</p></li><li><p>@uses, if this class depends on other packages</p></li><li><p>@see, if this class has related classes</p></li><li><p>@property, @property-read and @property-write are used to document properties of normal and <a href="#option-class">Option Class</a>.</p></li></ul><p>Example:</p><code class="block">/**
* One line description of the class.
*
@@ -519,10 +551,11 @@ public function __construct( $email, $na
/**
* File containing the <exception name> class
*
+ * [⦠license â¦]
+ *
* @package <packagename>
* @version //autogentag//
- * @copyright Copyright (C) 2005-2007 eZ systems as. All rights reserved.
- * @license http://ez.no/licenses/new_bsd New BSD License
+ * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
*/
/**
* Exception for <shortdesc>.
@@ -623,7 +656,7 @@ public function __get( $name )</code><p>
* Holds the properties of this class.
*
* @var array(string=>mixed)
- */</code><a name="documenting-private-classes"></a><h5>Documenting private classes</h5><p>If you are documenting a private class make sure to mark both the file and the class docblock with @access private. Documentation for these classes will <em>not</em> be generated for the end user documentation.</p><p>It is important that private classes are not exposed anywhere within the public classes.</p><a name="documenting-options"></a><h5>Documenting options</h5><p>Options should be documented in the class doc block as properties of the option class. It should follow directly after the main description. See <a href="#property-documentation">Property Documentation</a> for more information.</p><a name="phpdocumentor-tags-and-required-usage"></a><h5>phpDocumentor tags and required usage</h5><dl><dt>@apichange</dt><dd>Use this in any form of block level to document something that can be removed or changed when we bump the major version number of a component.</dd><dt>@category</dt><dd
>Required in the page level doc blocks in source files of tie-in packages. That is packages directly related to some main package where the separation exists only to avoid dependencies.</dd><dt>@copyright</dt><dd>Required in either the page or class level doc blocks. It should be in the form:</dd><dt>@deprecated</dt><dd>Required to use for everything that is deprecated. If a complete page or class is deprecated you should add this tag only to the page or class level doc block.</dd><dt>@example</dt><dd>Optional usage when making big examples. These can be in source files which we can then actually check for correct behavior.</dd><dt>@filesource</dt><dd>Required in the page level documentation.</dd><dt>@global</dt><dd>Required when creating global variables. I can't think of any reasons why we would want to create that though.</dd><dt>@ignore</dt><dd>Use if needed. __set, __get and __isset method documentation always get this tag.</dd><dt>@internal</dt><dd>Required when docume
nting public functionality and you want to add information that is developer specific.</dd><dt>@license</dt><dd>Required for the documentation of all files. It should always read:<code class="block">@license http://ez.no/licenses/new_bsd New BSD License</code></dd><dt>@link</dt><dd>Required when linking in the documentation.</dd><dt>@package</dt><dd>Required in the page level doc block of all source files. Always use the package name.</dd><dt>@param</dt><dd>Required for all function parameters. The type and variable name parameters are required. The description should be used if the purpose of the parameter is not mentioned in the method description. Documentation of parameters in the description is recommended.</dd><dt>@return</dt><dd>Required for all methods, and the type parameter is required. This tag should not exist for non-returning methods. The description should be used if the purpose of the return value is not mentioned in the method description.</dd><dt>@see</dt><
dd>Required to use when documenting methods or classes that have similar purpose.</dd><dt>@since</dt><dd>Required when adding new functionality to a package after the initial release.</dd><dt>@throws</dt><dd>Required for all methods that can throw an exception. You should also mention any exceptions that might bubble up.</dd><dt>@todo</dt><dd>Required to use when functionality is not finished. Packages should never contain TODO items when they are released.</dd><dt>@uses</dt><dd>Required for classes that have dependencies on other packages. The use should display what package you use. Should only be used in class documentation.</dd><dt>@var</dt><dd>Required for all class variables. The only allowed syntax is:<code class="block">/**
+ */</code><a name="documenting-private-classes"></a><h5>Documenting private classes</h5><p>If you are documenting a private class make sure to mark both the file and the class docblock with @access private. Documentation for these classes will <em>not</em> be generated for the end user documentation.</p><p>It is important that private classes are not exposed anywhere within the public classes.</p><a name="documenting-options"></a><h5>Documenting options</h5><p>Options should be documented in the class doc block as properties of the option class. It should follow directly after the main description. See <a href="#property-documentation">Property Documentation</a> for more information.</p><a name="phpdocumentor-tags-and-required-usage"></a><h5>phpDocumentor tags and required usage</h5><dl><dt>@apichange</dt><dd>Use this in any form of block level to document something that can be removed or changed when we bump the major version number of a component.</dd><dt>@category</dt><dd
>Required in the page level doc blocks in source files of tie-in packages. That is packages directly related to some main package where the separation exists only to avoid dependencies.</dd><dt>@copyright</dt><dd>Required in either the page or class level doc blocks. It should be in the form:</dd><dt>@deprecated</dt><dd>Required to use for everything that is deprecated. If a complete page or class is deprecated you should add this tag only to the page or class level doc block.</dd><dt>@example</dt><dd>Optional usage when making big examples. These can be in source files which we can then actually check for correct behavior.</dd><dt>@filesource</dt><dd>Required in the page level documentation.</dd><dt>@global</dt><dd>Required when creating global variables. I can't think of any reasons why we would want to create that though.</dd><dt>@ignore</dt><dd>Use if needed. __set, __get and __isset method documentation always get this tag.</dd><dt>@internal</dt><dd>Required when docume
nting public functionality and you want to add information that is developer specific.</dd><dt>@license</dt><dd>Required for the documentation of all files. It should always read:<code class="block">@license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0</code></dd><dt>@link</dt><dd>Required when linking in the documentation.</dd><dt>@package</dt><dd>Required in the page level doc block of all source files. Always use the package name.</dd><dt>@param</dt><dd>Required for all function parameters. The type and variable name parameters are required. The description should be used if the purpose of the parameter is not mentioned in the method description. Documentation of parameters in the description is recommended.</dd><dt>@return</dt><dd>Required for all methods, and the type parameter is required. This tag should not exist for non-returning methods. The description should be used if the purpose of the return value is not mentioned in the method descri
ption.</dd><dt>@see</dt><dd>Required to use when documenting methods or classes that have similar purpose.</dd><dt>@since</dt><dd>Required when adding new functionality to a package after the initial release.</dd><dt>@throws</dt><dd>Required for all methods that can throw an exception. You should also mention any exceptions that might bubble up.</dd><dt>@todo</dt><dd>Required to use when functionality is not finished. Packages should never contain TODO items when they are released.</dd><dt>@uses</dt><dd>Required for classes that have dependencies on other packages. The use should display what package you use. Should only be used in class documentation.</dd><dt>@var</dt><dd>Required for all class variables. The only allowed syntax is:<code class="block">/**
* Short description
* Longer description that can also span multiple lines, like
* this.
Modified: incubator/zetacomponents/website/htdocs/community/implementation.txt
URL: http://svn.apache.org/viewvc/incubator/zetacomponents/website/htdocs/community/implementation.txt?rev=1032125&r1=1032124&r2=1032125&view=diff
==============================================================================
--- incubator/zetacomponents/website/htdocs/community/implementation.txt (original)
+++ incubator/zetacomponents/website/htdocs/community/implementation.txt Sat Nov 6 18:01:32 2010
@@ -967,10 +967,26 @@ The option class itself, could look like
/**
* File containing the ezcFooBar class
*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ *
* @package Mail
* @version //autogen//
- * @copyright Copyright (C) 2005-2007 eZ systems as. All rights reserved.
- * @license http://ez.no/licenses/new_bsd New BSD License
+ * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
*/
/**
@@ -1188,15 +1204,16 @@ In general the examples show in what ord
File documentation
------------------
-Required in all source files with and without a class. PHPDocumentor will
-show a warning message otherwise.
+
+Required in all source files with and without a class. PHPDocumentor will show
+a warning message otherwise. In addition, the license information must be
+available in **all files**.
The following fields are required:
- A short (one line) description of the file.
- @version
- @package
-- @copyright
- @license
The following fields are optional:
@@ -1206,16 +1223,35 @@ The following fields are optional:
- @subpackage Tests
To be used for files/classes that make out a part of the test suite.
+The following fields may not occur:
+
+- @copyright
Example: ::
/**
* Short description of the contents of the file.
*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ *
* @version //autogen//
* @package PackageName
- * @copyright Copyright (C) 2005-2007 eZ systems as. All rights reserved.
- * @license http://ez.no/licenses/new_bsd New BSD License
+ * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
*/
Class documentation
@@ -1295,10 +1331,11 @@ Exception class documentation follows th
/**
* File containing the <exception name> class
*
+ * [⦠license â¦]
+ *
* @package <packagename>
* @version //autogentag//
- * @copyright Copyright (C) 2005-2007 eZ systems as. All rights reserved.
- * @license http://ez.no/licenses/new_bsd New BSD License
+ * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
*/
/**
* Exception for <shortdesc>.
@@ -1589,8 +1626,8 @@ phpDocumentor tags and required usage
@license
Required for the documentation of all files. It should always read::
-
- @license http://ez.no/licenses/new_bsd New BSD License
+
+ @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
@link
Required when linking in the documentation.
Modified: incubator/zetacomponents/website/htdocs/documentation/install.html
URL: http://svn.apache.org/viewvc/incubator/zetacomponents/website/htdocs/documentation/install.html?rev=1032125&r1=1032124&r2=1032125&view=diff
==============================================================================
--- incubator/zetacomponents/website/htdocs/documentation/install.html (original)
+++ incubator/zetacomponents/website/htdocs/documentation/install.html Sat Nov 6 18:01:32 2010
@@ -12,13 +12,13 @@
<meta name="keywords" content="PHP, apache, components, framework, quality" />
<meta name="author" content="Tobias Schlitt" />
<meta name="language" content="en" />
- <meta name="date" content="Wed, 04 Aug 2010 13:13:41 +0200" />
+ <meta name="date" content="Sat, 06 Nov 2010 18:17:26 +0100" />
<meta name="robots" content="all" />
<link rel="schema.DC" href="http://purl.org/dc/elements/1.1/" />
<meta name="DC.title" content="Installation" />
<meta name="DC.creator" content="Tobias Schlitt" />
- <meta name="DC.date" content="Wed, 04 Aug 2010 13:13:41 +0200" />
+ <meta name="DC.date" content="Sat, 06 Nov 2010 18:17:26 +0100" />
<meta name="DC.rights" content="Copyright" />
<link rel="meta" href="/zetacomponents/documentation/install.rdf" />
@@ -68,7 +68,7 @@
<div class="content">
- <h2>An Introduction to Apache Zeta Components</h2><div class="note"><p>This document has to be refactored to cosistently refer to Apache Zeta Components and the Apache Foundation instead of eZ*.</p></div><p>This guide provides a glimpse into the usage of the eZ Components for PHP 5. They are object oriented and reusable building blocks which will speed up development and deployment of enterprise applications based on PHP 5.</p><a name="what-is-it"></a><h3>What is it?</h3><p>eZ Components is an enterprise ready general purpose PHP components library. As a collection of high quality independent building blocks for PHP application development eZ Components will both speed up development and reduce risks. An application can use one or more components effortlessly as they all adhere to the same naming conventions and follow the same structure. All components are currently based on PHP 5.2.1.</p><p>The eZ Components in a nutshell:</p><ul><li><p>Designed for enterprise PHP applic
ation development</p></li><li><p>Open source and licensed under the <a href="/zetacomponents/overview/license">New BSD license</a></p></li><li><p>Clear intellectual property (IP) rights</p></li><li><p>Thoroughly documented</p></li><li><p>Developed, supported and maintained by <a href="http://ez.no">eZ Systems</a></p></li></ul><p>More general information about the eZ Components is available at the product page. Furthermore, there is a list of available components. Technical aspects of how the library is built-up are explained at the technical details page.</p><a name="usage"></a><h3>Usage</h3><p>The purpose of the eZ Components is to hide complexity of routines behind an object oriented API. Regular tasks of programming become much easier, and due to the fact that complexity is being reduced, the risk of application development is minimized. In general, your development process will become more efficient.</p><p>For example, sending an email with the help of the eZ Mail compon
ent, looks like this:</p><code class="block"><?php
+ <h2>An Introduction to Apache Zeta Components</h2><p>This guide provides a glimpse into the usage of the Apache Zeta Components for PHP 5. They are object oriented and reusable building blocks which will speed up development and deployment of enterprise applications based on PHP 5.</p><a name="what-is-it"></a><h3>What is it?</h3><p>Apache Zeta Components is an enterprise ready general purpose PHP components library. As a collection of high quality independent building blocks for PHP application development Apache Zeta Components will both speed up development and reduce risks. An application can use one or more components effortlessly as they all adhere to the same naming conventions and follow the same structure. All components are currently based on PHP 5.2.1.</p><p>The Apache Zeta Components in a nutshell:</p><ul><li><p>Designed for enterprise PHP application development</p></li><li><p>Open source and licensed under the <a href="http://www.apache.org/licenses/LICENSE-2
.0">Apache License, Version 2.0</a></p></li><li><p>Clear intellectual property (IP) rights</p></li><li><p>Thoroughly documented</p></li><li><p>Fully maintained by the open source community, initially developed by <a href="http://ez.no">eZ Systems</a></p></li></ul><a name="usage"></a><h3>Usage</h3><p>The purpose of Apache Zeta Components is to hide complexity of routines behind an object oriented API. Regular tasks of programming become much easier, and due to the fact that complexity is being reduced, the risk of application development is minimized. In general, your development process will become more efficient.</p><p>For example, sending an email with the help of the Zeta Mail component, looks like this:</p><code class="block"><?php
try
{
$transport = new ezcMailTransportSmtp( "smtp.example.com" );
@@ -78,33 +78,36 @@ try
$mail->subject = "[Components test] SMTP test";
$mail->body = new ezcMailText( "Content" );
$transport->send( $mail );
-
}
-
catch ( Exception $e )
{
echo "Failed: ", $e->getMessage(), "\n";
}
-?></code><p>Of course you need to change the SMTP server's IP ( smtp.example.com) and definitely the email adresses in the sample code to fit your needs. For more examples of each of the eZ Components, take a look at the doc/ directory of each component where some sample code is provided.</p><p>Please notice that the eZ Components will only work on PHP 5.2.1 or higher. They can be used side-by-side with PEAR packages that as well run on PHP >= 5.2.1.</p><a name="installation"></a><h3>Installation</h3><p>There are three ways how to make eZ components available for your PHP environment, please read the whole of this article before continuing with the practical part:</p><ul><li><p>Use <a href="http://pear.php.net">PEAR Installer</a> for convenient installation via command line</p></li><li><p><a href="/zetacomponents/download">Download</a> eZ components packaged in an archive</p></li><li><p>Get the latest sources from SVN</p></li></ul><p>Installing the eZ components with t
he help of the PEAR Installer is highly recommended, as it is the most convenient and safest way. The given instructions serve as guidelines on a Linux system, but are also useful for those who run PHP on Windows, of course they just need to adjust the paths accordingly.</p><a name="id1"></a><h4>PEAR Installer</h4><p>After you have installed PHP 5.2.1 or a higher version, you will have the PEAR Installer available automatically. Simply issue the following commands in the shell:</p><code class="block">pear channel-discover components.ez.no</code><p>This will let PEAR Installer connect to the server components.ez.no where the eZ components are stored for distribution:</p><code class="block">pear install -a ezc/eZComponents</code><p>This final command will download and typically extract all eZ components to the directory where also the PEAR packages reside, but beneath the ezc/ subdirectory, with the absolute path being: /path/to/pear/ezc/</p><p>In case you already have install
ed the components before, you can simply do:</p><code class="block">pear upgrade ezc/eZComponents</code><a name="download-of-archives"></a><h4>Download of Archives</h4><p>The packaged releases of eZ components can be downloaded as .tar.bz2 or .zip archive from the <a href="/zetacomponents/download">download</a> page. The bundles that we offer for download always include the whole library.</p><a name="svn"></a><h3>SVN</h3><p>If you love to live on the edge and would like to work with the latest development version of the eZ components, you can get it from SVN. For a successful installation from SVN, procede in the given order.</p><p>First, create a directory where you want the eZ components to be placed.</p><p>Next, you should checkout the tree. To checkout, do:</p><code class="block">svn co http://svn.ez.no/svn/ezcomponents/trunk</code><p>When working with the SVN version, it is important to setup the environment for the eZ components. Hence, checkout the needed script with:
</p><code class="block">svn co http://svn.ez.no/svn/ezcomponents/scripts</code><p>and execute it:</p><code class="block">./scripts/setup-env.sh</code><p>This will create the symlinks for autoload, which will of course not work on Windows.</p><p>From version 1.1 of the components there is also a script for Windows. Here you need to execute the following script instead:</p><code class="block">scripts\setup-env.bat</code><p>This will create copies of necessary files for autoload.</p><a name="partial-check-out"></a><h4>Partial check out</h4><p>It is of course also possible to check out from SVN per component. Again, you first have to create a directory again, something like:</p><code class="block">mkdir /tmp/mydir/ezc
-cd /tmp/mydir/ezc</code><p>Inside this directory, create the trunk directory:</p><code class="block">mkdir trunk</code><p>Then check out the scripts directory and Base component:</p><code class="block">svn co http://svn.ez.no/svn/ezcomponents/scripts
-svn co http://svn.ez.no/svn/ezcomponents/trunk/Base trunk/Base</code><p>Then you can check out each component that you want with a command like:</p><code class="block">svn co http://svn.ez.no/svn/ezcomponents/trunk/Mail trunk/Mail</code><p>Make sure to checkout all dependencies as well, if they exist. You can find whether a component has dependencies in the DEPS file in the root of each component (f.e. trunk/Mail/DEPS).</p><p>After you've checked out all components, run the setup-env script again:</p><code class="block">./scripts/setup-env.sh</code><p>or:</p><code class="block">scripts\setup-env.bat</code><a name="configuration"></a><h3>Configuration</h3><p>After installation of the eZ Components, either via PEAR Installer, downloading of the archives, or getting them from SVN, you need to do a bit of configuration:</p><ul><li><p>Adjust the include path to have the eZ Components classes available via PHP</p></li><li><p>Create the autoload environment for calling eZ Component
s from your script</p></li></ul><a name="include-path"></a><h4>Include Path</h4><p>The PHP include path should point to the directory where the eZ Components reside. You can either set it in the php.ini configuration file or with the set_include_path() function from within your script.</p><p>If you installed the components with the PEAR installer, then in most cases you do not have to make any changes as PHP's include path will already cover the default:</p><code class="block">/usr/local/lib/php</code><p>into which the PEAR installer will install the eZ Components. In case it is different, please set it at the top of your script with:</p><code class="block"><?php
-set_include_path( "/path/to/root/pear/directory" . PATH_SEPARATOR . get_include_path());
-?></code><p>In case you downloaded a bundle, or checked out the components from SVN, set the include path to the root of the checked out archive. For example with:</p><code class="block"><?php
-set_include_path( "/path/to/ezcomponents-1.0rc1" . PATH_SEPARATOR . get_include_path());
-?></code><a name="autoload-environment"></a><h4>Autoload Environment</h4><p>The PHP classes of the eZ Components can be conveniently used from within your PHP script. You don't have to use any require or include statements for any of the eZ Components classes that you use, this is because of the integrated autoload mechanism which can locate the classes for you when you instantiate or use them otherwise.</p><p>There are three different ways of getting the autoload mechanism going.</p><a name="normal-autoload"></a><h5>Normal Autoload</h5><p>With the first method, you require the ezcBase class, and defined your own autoload mechanism. You should add the following code on top of your PHP script:</p><code class="block"><?php
+?></code><p>Of course you need to change the SMTP server's IP (smtp.example.com) and definitely the email addresses in the sample code to fit your needs. For more examples of each of the Apache Zeta Components, take a look at the doc/ directory of each component where some sample code is provided.</p><p>Furthermore, extensive API documentation and a tutorial are provided online in the <a href="/zetacomponents/documentation/trunk.html">docs section</a>.</p><p>Please notice that the Apache Zeta Components will only work on PHP 5.2.1 or higher. They can be used side-by-side with, for example, PEAR packages and the Zend Framework, which as well run on PHP >= 5.2.1.</p><a name="installation"></a><h3>Installation</h3><p>There are three ways how to make Apache Zeta Components available for your PHP environment, please read the whole of this article before continuing with the practical part:</p><ul><li><p>Use <a href="http://pear.php.net">PEAR Installer</a> for convenient inst
allation via command line</p></li><li><p><a href="/zetacomponents/download">Download</a> Apache Zeta Components packaged in an archive</p></li><li><p>Get the latest sources from SVN</p></li></ul><div class="note"><p>There is no release of the project source as Apache Zeta Components, yet. We are working on making a release possible. In the mean while, please use the PEAR packages provided by the old eZ Components PEAR channel on <code class="inline">components.ez.no</code>, or download the full library package from the <a href="http://ezcomponents.org/download">old eZ Components website</a>. <strong>Apache Zeta Components are
+fully API compatible with eZ Components!</strong></p></div><p>Installing the Apache Zeta Components with the help of the PEAR Installer is highly recommended, as it is the most convenient and safest way. The given instructions serve as guidelines on a Linux system, but are also useful for those who run PHP on Windows, of course they just need to adjust the paths accordingly.</p><a name="pear-installer"></a><h4>PEAR Installer</h4><div class="note"><p>The following instructions still refer to the eZ Components PEAR channel, since Apache Zeta Components did not roll a release, yet. Apache Zeta Components are fully API compatible with the old (discontinued) eZ Components library.</p></div><p>After you have installed PHP 5.2.1 or a higher version, you will have the PEAR Installer available automatically. Simply issue the following commands in the shell:</p><code class="block">pear channel-discover components.ez.no</code><p>This will let PEAR Installer connect to the server compon
ents.ez.no where the eZ Components are stored for distribution:</p><code class="block">pear install -a ezc/eZComponents</code><p>This final command will download and typically extract all eZ components to the directory where also the PEAR packages reside, but beneath the ezc/ subdirectory, with the absolute path being: /path/to/pear/ezc/</p><p>In case you already have installed the components before, you can simply do:</p><code class="block">pear upgrade ezc/eZComponents</code><a name="download-of-archives"></a><h4>Download of Archives</h4><div class="note"><p>The following instructions still refer to the eZ Components download page, since Apache Zeta Components did not roll a release, yet. Apache Zeta Components are fully API compatible with the old (discontinued) eZ Components library.</p></div><p>The packaged releases of eZ components can be downloaded as .tar.bz2 or .zip archive from the <a href="http://ezcomponents.org/download">download page</a>. The bundles that we of
fer for download always include the whole library. You just need to extract the package and adjust your <code class="inline">include_path</code> directive.</p><a name="svn"></a><h3>SVN</h3><p>If you love to live on the edge and would like to work with the latest development version of Apache Zeta Components, you can get it from SVN. For a successful installation from SVN, proceed in the given order.</p><p>First, create a directory where you want the Apache Zeta Components to be placed.</p><p>Next, you should checkout the trunk, which contains the latest development sources. To checkout, do:</p><code class="block">svn co https://svn.apache.org/repos/asf/incubator/zetacomponents/trunk</code><p>When working with the SVN version, it is important to setup the environment for Apache Zeta Components. Hence, checkout the needed script with:</p><code class="block">svn co https://svn.apache.org/repos/asf/incubator/zetacomponents/scripts</code><p>and execute it:</p><code class="block">
./scripts/setup-env.sh</code><p>This will create the symlinks for autoload, which will of course not work on Windows. For this platform, the alternative script:</p><code class="block">scripts\setup-env.bat</code><p>will create copies of necessary files for autoload. Note that you will need to re-run this script whenever you performed SVN up (and new class have been added) or if you added new classes yourself. This step is not necessary on *nix systems.</p><a name="partial-check-out"></a><h4>Partial check out</h4><p>A per component check out from SVN is of course also possible. Again, you first have to create a directory again, something like:</p><code class="block">mkdir /tmp/mydir/ezc
+cd /tmp/mydir/ezc</code><p>Inside this directory, create the trunk directory:</p><code class="block">mkdir trunk</code><p>Then check out the scripts directory and Base component:</p><code class="block">svn co https://svn.apache.org/repos/asf/incubator/zetacomponents/scripts
+svn co https://svn.apache.org/repos/asf/incubator/zetacomponents/trunk/Base trunk/Base</code><p>Then you can check out each component that you want with a command like:</p><code class="block">svn co https://svn.apache.org/repos/asf/incubator/zetacomponents/trunk/Mail trunk/Mail</code><p>Make sure to checkout all dependencies as well, if they exist. You can find whether a component has dependencies in the DEPS file in the root of each component (f.e. trunk/Mail/DEPS).</p><p>After you've checked out all components, run the setup-env script again:</p><code class="block">./scripts/setup-env.sh</code><p>or:</p><code class="block">scripts\setup-env.bat</code><a name="configuration"></a><h3>Configuration</h3><p>After installation of Apache Zeta Components, either via PEAR Installer, downloading of the archives, or getting them from SVN, you need to do a bit of configuration:</p><ul><li><p>Adjust the <code class="inline">include_path</code> to have the Apache Zeta Components classes
available via PHP</p></li><li><p>Create the autoload environment for calling eZ Components from your script</p></li></ul><a name="include-path"></a><h4>Include Path</h4><p>The PHP include path should point to the directory where the Apache Zeta Components reside. You can either set it in the <em>php.ini</em> configuration file or with the <code class="inline">set_include_path()</code> function from within your script.</p><p>If you installed the components with the PEAR installer, then in most cases you do not have to make any changes as PHP's include path will already cover the default:</p><code class="block">/usr/local/lib/php</code><p>into which the PEAR installer will install the Apache Zeta Components. In case it is different, please set it at the top of your script with:</p><code class="block"> <?php
+ set_include_path(
+ '/path/to/root/pear/directory' . PATH_SEPARATOR . get_include_path()
+);
+ ?></code><p>In case you downloaded a bundle, or checked out the components from SVN, set the include path to the root of the checked out archive. For example with:</p><code class="block"> <?php
+ set_include_path(
+ '/path/to/ezcomponents-version' . PATH_SEPARATOR . get_include_path()
+);
+ ?></code><a name="autoload-environment"></a><h4>Autoload Environment</h4><p>The PHP classes of Apache Zeta Components can be conveniently used from within your PHP script. You don't have to use any <code class="inline">require</code> or <code class="inline">include</code> statements for any of the Apache Zeta Components classes that you use, this is because of the integrated autoload mechanism which can locate the classes for you when you instantiate or use them otherwise.</p><p>There are three different ways of getting the autoload mechanism going:</p><ul><li><p>Normal autoload, if you require a custom autoload function</p></li><li><p>Bootstrap file, if you only use Apache Zeta autoloading</p></li><li><p>SPL autoload, if you need to register several autoload functions</p></li></ul><a name="normal-autoload"></a><h5>Normal Autoload</h5><p>With the first method, you require the ezcBase class, and defined your own autoload mechanism. You should add the following code on
top of your PHP script:</p><code class="block"><?php
require_once "Base/base.php"; // dependent on installation method, see below
function __autoload( $className )
{
ezcBase::autoload( $className );
}
-// your code here
-?></code><p>Beware, that the require_once() statement is different depending on the installation method:</p><ul><li><p>PEAR Installer:</p><code class="block">ezc/Base/base.php</code></li><li><p>Downloaded bundle and SVN:</p><code class="block">Base/src/base.php</code></li></ul><a name="boot-strap"></a><h5>Boot strap</h5><p>In case you only have to use autoload for the eZ Components, and not for your application or another library, you can just simple include the <code class="inline">ezc_bootstrap.php</code> file. Again, the file to require depends on the installation method.</p><ul><li><p>PEAR Installer:</p><code class="block"><?php
+// your code here â¦
+?></code><p>Beware, that the <code class="inline">require_once()</code> statement is different depending on the installation method, due to the PEAR directory structure:</p><ul><li><p>PEAR Installer:</p><code class="block">ezc/Base/base.php</code></li><li><p>Downloaded bundle and SVN:</p><code class="block">Base/src/base.php</code></li></ul><a name="boot-strap"></a><h5>Boot strap</h5><p>In case you only have to use autoload for the Apache Zeta Components, and not for your application or another library, you can just simple include the <code class="inline">ezc_bootstrap.php</code> file. Again, the file to require depends on the installation method.</p><ul><li><p>PEAR Installer:</p><code class="block"><?php
require 'ezc/Base/ezc_bootstrap.php';
?></code></li><li><p>Downloaded bundle and SVN:</p><code class="block"><?php
require 'Base/src/ezc_bootstrap.php';
-?></code></li></ul><a name="spl"></a><h5>SPL</h5><p>SPL (Standard PHP Library) also allows autoloading to be set up through the <a href="http://php.net/manual/en/function.spl-autoload-register.php">spl_autoload_register</a> function. In this case, you require() the base class, just like in the <a href="#normal-autoload">Normal Autoload</a> method, but instead of defining an __autoload() function, you do:</p><code class="block"><?php
+?></code></li></ul><p><code class="inline">ezc_bootstrap.php</code> basically contains the code seen in the <a href="#normal-autoload">Normal Autoload</a> section.</p><a name="spl"></a><h5>SPL</h5><p><a href="http://php.net/spl">SPL</a> (Standard PHP Library) also allows autoloading to be set up through the <a href="http://php.net/manual/en/function.spl-autoload-register.php">spl_autoload_register</a> function. In this case, you <code class="inline">require</code> the base class, just like in the <a href="#normal-autoload">Normal Autoload</a> method, but instead of defining an <code class="inline">__autoload()</code> function, you do:</p><code class="block"><?php
spl_autoload_register( array( 'ezcBase', 'autoload' ) );
-?></code><a name="worth-knowing"></a><h3>Worth knowing</h3><a name="required-extensions"></a><h4>Required extensions</h4><p>eZ Components require as few extensions by default. Required by all components are:</p><ul><li><p><a href="http://php.net/spl">SPL</a></p></li><li><p><a href="http://php.net/iconv">iconv</a></p></li></ul><p>Both of these are bundled with PHP and activated by default. So if you did not actively remove these from your PHP installation manually, you don't have to care about them.</p><p>Specific components may require additional extensions, for example the database related components (<a href="/s/Database">Database</a>, <a href="/s/DatabaseSchema">DatabaseSchema</a>, <a href="/s/PersistentObject">PersistentObject</a>) rely on <a href="http://php.net/pdo">PDO</a> being available. The components documentation will give a hint, if special extensions are required. You can find a full overview in the <a href="/zetacomponents/introduction/requirements">documen
tation</a>.</p><p>Some components provide different drivers, which use different extensions or external programs. You can choose one of these to make the component use the backend that you have available. An example is the <a href="/s/Graph">Graph</a> component, which can use different extensions to render graphics in different formats.</p><a name="character-encoding"></a><h4>Character encoding</h4><p>If not stated otherwise in the documentation, eZ Components assumes that the data that you provide is <a href="http://en.wikipedia.org/wiki/Utf-8">UTF-8</a> encoded. In the same way, the output and return values generated by each are UTF-8 encoded as well.</p><p>If you need to work with data in different encodings, make sure to convert this data to UTF-8 before handing it into any of the components.</p><p>To perform binary safe operations, the <a href="http://php.net/iconv">iconv</a> extension is used internally in eZ Components. As mentioned before, this extension is delivered
with PHP and activated by default. We recommend that you use this extension also for potential encoding conversions.</p><p>Some components allow you to work with different encodings than UTF-8. For example, the <a href="http://ezcomponents.org/s/Mail">Mail</a> component can work with several different encodings in parallel. Such exceptions of the rule are clearly marked in the documentation.</p><a name="conclusion"></a><h3>Conclusion</h3><p>Now you have a working environment which lets you integrate the object oriented eZ Components for efficient application development with PHP 5.2.1. Besides using the eZ Components for developing your own mission-critical applications, you can as well take a look at the source code to see how eZ Systems makes use of the new PHP 5 features for object oriented programming within the eZ Components. Have a lot of fun!</p><a name="resources"></a><h3>Resources</h3><ul><li><p><a href="/zetacomponents/news.html">General information page</a></p></
li><li><p><a href="/zetacomponents/documentation/trunk.html">List of available components</a></p></li><li><p>Browse the eZ Components <a href="https://fisheye6.atlassian.com/browse/zetacomponents/trunk/">source code online</a></p></li><li><p>Issues of eZ Components development are being discussed in the <a href="/zetacomponents/community/index.html#mailing-lists">eZ Components developers mailinglist</a></p></li></ul><!--Local Variables:
+?></code><p>This way, you can register additional autoload functions for your own application or additional libraries.</p><a name="worth-knowing"></a><h3>Worth knowing</h3><p>In following, we present some additional information on Apache Zeta Components, which you should know when starting to work with the library.</p><a name="required-extensions"></a><h4>Required extensions</h4><p>Apache Zeta Components require as few extensions by default. Required by all components are:</p><ul><li><p><a href="http://php.net/spl">SPL</a></p></li><li><p><a href="http://php.net/iconv">iconv</a></p></li></ul><p>Both of these are bundled with PHP and activated by default. So if you did not actively remove these from your PHP installation manually, you don't have to care about them.</p><p>Specific components may require additional extensions, for example the database related components (<a href="http://zetac.org/Database">Database</a>, <a href="http://zetac.org/DatabaseSchema">DatabaseSchema
</a>, <a href="http://zetac.org/PersistentObject">PersistentObject</a>) rely on <a href="http://php.net/pdo">PDO</a> being available. The components documentation will give a hint, if special extensions are required.</p><p>Some components provide different drivers, which use different extensions or external programs. You can choose one of these to make the component use the back end that you have available. An example is the <a href="http://zetac.org/Graph">Graph</a> component, which can use different extensions to render graphics in different formats.</p><a name="character-encoding"></a><h4>Character encoding</h4><p>If not stated otherwise in the documentation, Apache Zeta Components assume that the data that you provide is <a href="http://en.wikipedia.org/wiki/Utf-8">UTF-8</a> encoded. In the same way, the output and return values generated by each are UTF-8 encoded as well.</p><p>If you need to work with data in different encodings, make sure to convert this data to UTF-8
before handing it into any of the components.</p><p>To perform binary safe operations, the <a href="http://php.net/iconv">iconv</a> extension is used internally in Apache Zeta Components. As mentioned before, this extension is delivered with PHP and activated by default. We recommend that you use this extension also for potential encoding conversions.</p><p>Some components allow you to work with different encodings than UTF-8. For example, the <a href="http://zetac.org/Mail">Mail</a> component can work with several different encodings in parallel. Such exceptions of the rule are clearly marked in the documentation.</p><a name="conclusion"></a><h3>Conclusion</h3><p>Now you have a working environment which lets you integrate the object oriented Apache Zeta Components for efficient application development with PHP 5.2.1. Besides using the Apache Zeta Components for developing your own mission-critical applications, you can as well take a look at the source code to see how Apac
he Zeta Components make use of the new PHP 5 features for object oriented programming. Have a lot of fun!</p><a name="resources"></a><h3>Resources</h3><ul><li><p><a href="/zetacomponents/news.html">General information page</a></p></li><li><p><a href="/zetacomponents/documentation/trunk.html">List of available components</a></p></li><li><p>Browse the eZ Components <a href="https://fisheye6.atlassian.com/browse/zetacomponents/trunk/">source code online</a></p></li><li><p>Issues of eZ Components development are being discussed in the <a href="/zetacomponents/community/index.html#mailing-lists">eZ Components developers mailinglist</a></p></li></ul><!--Local Variables:
mode: rst
fill-column: 79
End:
Modified: incubator/zetacomponents/website/htdocs/documentation/install.txt
URL: http://svn.apache.org/viewvc/incubator/zetacomponents/website/htdocs/documentation/install.txt?rev=1032125&r1=1032124&r2=1032125&view=diff
==============================================================================
--- incubator/zetacomponents/website/htdocs/documentation/install.txt (original)
+++ incubator/zetacomponents/website/htdocs/documentation/install.txt Sat Nov 6 18:01:32 2010
@@ -1,49 +1,42 @@
An Introduction to Apache Zeta Components
=========================================
-.. note::
- This document has to be refactored to cosistently refer to Apache Zeta
- Components and the Apache Foundation instead of eZ*.
-
-This guide provides a glimpse into the usage of the eZ Components for PHP 5.
-They are object oriented and reusable building blocks which will speed up
-development and deployment of enterprise applications based on PHP 5.
+This guide provides a glimpse into the usage of the Apache Zeta Components for
+PHP 5. They are object oriented and reusable building blocks which will speed
+up development and deployment of enterprise applications based on PHP 5.
What is it?
-----------
-eZ Components is an enterprise ready general purpose PHP components library. As
-a collection of high quality independent building blocks for PHP application
-development eZ Components will both speed up development and reduce risks. An
-application can use one or more components effortlessly as they all adhere to
-the same naming conventions and follow the same structure. All components are
-currently based on PHP 5.2.1.
-
-The eZ Components in a nutshell:
-
-* Designed for enterprise PHP application development
-* Open source and licensed under the `New BSD license`_
-* Clear intellectual property (IP) rights
-* Thoroughly documented
-* Developed, supported and maintained by `eZ Systems`_
-
-More general information about the eZ Components is available at the product
-page. Furthermore, there is a list of available components. Technical aspects
-of how the library is built-up are explained at the technical details page.
+Apache Zeta Components is an enterprise ready general purpose PHP components
+library. As a collection of high quality independent building blocks for PHP
+application development Apache Zeta Components will both speed up development
+and reduce risks. An application can use one or more components effortlessly as
+they all adhere to the same naming conventions and follow the same structure.
+All components are currently based on PHP 5.2.1.
+
+The Apache Zeta Components in a nutshell:
+
+- Designed for enterprise PHP application development
+- Open source and licensed under the `Apache License, Version 2.0`__
+- Clear intellectual property (IP) rights
+- Thoroughly documented
+- Fully maintained by the open source community, initially developed by `eZ
+ Systems`__
-.. _`New BSD License`: /zetacomponents/overview/license
-.. _`eZ Systems`: http://ez.no
+__ http://www.apache.org/licenses/LICENSE-2.0
+__ http://ez.no
Usage
-----
-The purpose of the eZ Components is to hide complexity of routines behind an
-object oriented API. Regular tasks of programming become much easier, and due
-to the fact that complexity is being reduced, the risk of application
+The purpose of Apache Zeta Components is to hide complexity of routines behind
+an object oriented API. Regular tasks of programming become much easier, and
+due to the fact that complexity is being reduced, the risk of application
development is minimized. In general, your development process will become more
efficient.
-For example, sending an email with the help of the eZ Mail component, looks
+For example, sending an email with the help of the Zeta Mail component, looks
like this::
<?php
@@ -56,40 +49,52 @@ like this::
$mail->subject = "[Components test] SMTP test";
$mail->body = new ezcMailText( "Content" );
$transport->send( $mail );
-
}
-
catch ( Exception $e )
{
echo "Failed: ", $e->getMessage(), "\n";
}
?>
-Of course you need to change the SMTP server's IP ( smtp.example.com) and
-definitely the email adresses in the sample code to fit your needs. For more
-examples of each of the eZ Components, take a look at the doc/ directory of
-each component where some sample code is provided.
-
-Please notice that the eZ Components will only work on PHP 5.2.1 or higher.
-They can be used side-by-side with PEAR packages that as well run on PHP >=
-5.2.1.
+Of course you need to change the SMTP server's IP (smtp.example.com) and
+definitely the email addresses in the sample code to fit your needs. For more
+examples of each of the Apache Zeta Components, take a look at the doc/
+directory of each component where some sample code is provided.
+
+Furthermore, extensive API documentation and a tutorial are provided online in
+the `docs section`__.
+
+__ /zetacomponents/documentation/trunk.html
+
+Please notice that the Apache Zeta Components will only work on PHP 5.2.1 or
+higher. They can be used side-by-side with, for example, PEAR packages and the
+Zend Framework, which as well run on PHP >= 5.2.1.
Installation
------------
-There are three ways how to make eZ components available for your PHP
+There are three ways how to make Apache Zeta Components available for your PHP
environment, please read the whole of this article before continuing with the
practical part:
-* Use `PEAR Installer`_ for convenient installation via command line
-* Download_ eZ components packaged in an archive
+* Use `PEAR Installer`__ for convenient installation via command line
+* Download__ Apache Zeta Components packaged in an archive
* Get the latest sources from SVN
-.. _`PEAR Installer`: http://pear.php.net
-.. _download: /zetacomponents/download
+__ http://pear.php.net
+__ /zetacomponents/download
+
+.. note:: There is no release of the project source as Apache Zeta Components,
+ yet. We are working on making a release possible. In the mean while,
+ please use the PEAR packages provided by the old eZ Components PEAR
+ channel on ``components.ez.no``, or download the full library package
+ from the `old eZ Components website`__. **Apache Zeta Components are
+ fully API compatible with eZ Components!**
+
+ __ http://ezcomponents.org/download
-Installing the eZ components with the help of the PEAR Installer is highly
-recommended, as it is the most convenient and safest way. The given
+Installing the Apache Zeta Components with the help of the PEAR Installer is
+highly recommended, as it is the most convenient and safest way. The given
instructions serve as guidelines on a Linux system, but are also useful for
those who run PHP on Windows, of course they just need to adjust the paths
accordingly.
@@ -97,6 +102,11 @@ accordingly.
PEAR Installer
~~~~~~~~~~~~~~
+.. note:: The following instructions still refer to the eZ Components PEAR
+ channel, since Apache Zeta Components did not roll a release, yet.
+ Apache Zeta Components are fully API compatible with the old
+ (discontinued) eZ Components library.
+
After you have installed PHP 5.2.1 or a higher version, you will have the PEAR
Installer available automatically. Simply issue the following commands in the
shell::
@@ -104,7 +114,7 @@ shell::
pear channel-discover components.ez.no
This will let PEAR Installer connect to the server components.ez.no where the
-eZ components are stored for distribution::
+eZ Components are stored for distribution::
pear install -a ezc/eZComponents
@@ -119,47 +129,57 @@ In case you already have installed the c
Download of Archives
~~~~~~~~~~~~~~~~~~~~
+.. note:: The following instructions still refer to the eZ Components download
+ page, since Apache Zeta Components did not roll a release, yet.
+ Apache Zeta Components are fully API compatible with the old
+ (discontinued) eZ Components library.
+
The packaged releases of eZ components can be downloaded as .tar.bz2 or .zip
-archive from the download_ page. The bundles that we offer for download always
-include the whole library.
+archive from the `download page`__. The bundles that we offer for download
+always include the whole library. You just need to extract the package and
+adjust your ``include_path`` directive.
+
+__ http://ezcomponents.org/download
SVN
---
If you love to live on the edge and would like to work with the latest
-development version of the eZ components, you can get it from SVN. For a
-successful installation from SVN, procede in the given order.
+development version of Apache Zeta Components, you can get it from SVN. For a
+successful installation from SVN, proceed in the given order.
-First, create a directory where you want the eZ components to be placed.
+First, create a directory where you want the Apache Zeta Components to be
+placed.
-Next, you should checkout the tree. To checkout, do::
+Next, you should checkout the trunk, which contains the latest development
+sources. To checkout, do::
- svn co http://svn.ez.no/svn/ezcomponents/trunk
+ svn co https://svn.apache.org/repos/asf/incubator/zetacomponents/trunk
When working with the SVN version, it is important to setup the environment for
-the eZ components. Hence, checkout the needed script with::
+Apache Zeta Components. Hence, checkout the needed script with::
- svn co http://svn.ez.no/svn/ezcomponents/scripts
+ svn co https://svn.apache.org/repos/asf/incubator/zetacomponents/scripts
and execute it::
./scripts/setup-env.sh
This will create the symlinks for autoload, which will of course not work on
-Windows.
-
-From version 1.1 of the components there is also a script for Windows. Here you
-need to execute the following script instead::
+Windows. For this platform, the alternative script::
scripts\setup-env.bat
-This will create copies of necessary files for autoload.
+will create copies of necessary files for autoload. Note that you will need to
+re-run this script whenever you performed SVN up (and new class have been
+added) or if you added new classes yourself. This step is not necessary on
+\*nix systems.
Partial check out
~~~~~~~~~~~~~~~~~
-It is of course also possible to check out from SVN per component. Again, you
-first have to create a directory again, something like::
+A per component check out from SVN is of course also possible. Again, you first
+have to create a directory again, something like::
mkdir /tmp/mydir/ezc
cd /tmp/mydir/ezc
@@ -170,12 +190,12 @@ Inside this directory, create the trunk
Then check out the scripts directory and Base component::
- svn co http://svn.ez.no/svn/ezcomponents/scripts
- svn co http://svn.ez.no/svn/ezcomponents/trunk/Base trunk/Base
+ svn co https://svn.apache.org/repos/asf/incubator/zetacomponents/scripts
+ svn co https://svn.apache.org/repos/asf/incubator/zetacomponents/trunk/Base trunk/Base
Then you can check out each component that you want with a command like::
- svn co http://svn.ez.no/svn/ezcomponents/trunk/Mail trunk/Mail
+ svn co https://svn.apache.org/repos/asf/incubator/zetacomponents/trunk/Mail trunk/Mail
Make sure to checkout all dependencies as well, if they exist. You can find
whether a component has dependencies in the DEPS file in the root of each
@@ -189,23 +209,23 @@ or::
scripts\setup-env.bat
-
Configuration
-------------
-After installation of the eZ Components, either via PEAR Installer, downloading
-of the archives, or getting them from SVN, you need to do a bit of
+After installation of Apache Zeta Components, either via PEAR Installer,
+downloading of the archives, or getting them from SVN, you need to do a bit of
configuration:
-* Adjust the include path to have the eZ Components classes available via PHP
-* Create the autoload environment for calling eZ Components from your script
+- Adjust the ``include_path`` to have the Apache Zeta Components classes
+ available via PHP
+- Create the autoload environment for calling eZ Components from your script
Include Path
~~~~~~~~~~~~
-The PHP include path should point to the directory where the eZ Components
-reside. You can either set it in the php.ini configuration file or with the
-set_include_path() function from within your script.
+The PHP include path should point to the directory where the Apache Zeta
+Components reside. You can either set it in the *php.ini* configuration file or
+with the ``set_include_path()`` function from within your script.
If you installed the components with the PEAR installer, then in most cases you
do not have to make any changes as PHP's include path will already cover the
@@ -213,36 +233,45 @@ default::
/usr/local/lib/php
-into which the PEAR installer will install the eZ Components. In case it is
-different, please set it at the top of your script with::
+into which the PEAR installer will install the Apache Zeta Components. In case
+it is different, please set it at the top of your script with::
<?php
- set_include_path( "/path/to/root/pear/directory" . PATH_SEPARATOR . get_include_path());
+ set_include_path(
+ '/path/to/root/pear/directory' . PATH_SEPARATOR . get_include_path()
+ );
?>
In case you downloaded a bundle, or checked out the components from SVN, set
the include path to the root of the checked out archive. For example with::
<?php
- set_include_path( "/path/to/ezcomponents-1.0rc1" . PATH_SEPARATOR . get_include_path());
+ set_include_path(
+ '/path/to/ezcomponents-version' . PATH_SEPARATOR . get_include_path()
+ );
?>
Autoload Environment
~~~~~~~~~~~~~~~~~~~~
-The PHP classes of the eZ Components can be conveniently used from within your
-PHP script. You don't have to use any require or include statements for any of
-the eZ Components classes that you use, this is because of the integrated
-autoload mechanism which can locate the classes for you when you instantiate or
-use them otherwise.
-
-There are three different ways of getting the autoload mechanism going.
+The PHP classes of Apache Zeta Components can be conveniently used from within
+your PHP script. You don't have to use any ``require`` or ``include``
+statements for any of the Apache Zeta Components classes that you use, this is
+because of the integrated autoload mechanism which can locate the classes for
+you when you instantiate or use them otherwise.
+
+There are three different ways of getting the autoload mechanism going:
+
+- Normal autoload, if you require a custom autoload function
+- Bootstrap file, if you only use Apache Zeta autoloading
+- SPL autoload, if you need to register several autoload functions
Normal Autoload
```````````````
With the first method, you require the ezcBase class, and defined your own
-autoload mechanism. You should add the following code on top of your PHP script::
+autoload mechanism. You should add the following code on top of your PHP
+script::
<?php
require_once "Base/base.php"; // dependent on installation method, see below
@@ -250,61 +279,70 @@ autoload mechanism. You should add the f
{
ezcBase::autoload( $className );
}
- // your code here
+ // your code here â¦
?>
-Beware, that the require_once() statement is different depending on the
-installation method:
+Beware, that the ``require_once()`` statement is different depending on the
+installation method, due to the PEAR directory structure:
-* PEAR Installer::
+- PEAR Installer::
ezc/Base/base.php
-* Downloaded bundle and SVN::
+- Downloaded bundle and SVN::
Base/src/base.php
Boot strap
``````````
-In case you only have to use autoload for the eZ Components, and not for your
-application or another library, you can just simple include the
+In case you only have to use autoload for the Apache Zeta Components, and not
+for your application or another library, you can just simple include the
``ezc_bootstrap.php`` file. Again, the file to require depends on the
installation method.
-* PEAR Installer::
+- PEAR Installer::
<?php
require 'ezc/Base/ezc_bootstrap.php';
?>
-* Downloaded bundle and SVN::
+- Downloaded bundle and SVN::
<?php
require 'Base/src/ezc_bootstrap.php';
?>
+``ezc_bootstrap.php`` basically contains the code seen in the `Normal
+Autoload`_ section.
+
SPL
```
-SPL (Standard PHP Library) also allows autoloading to be set up through the
-spl_autoload_register_ function. In this case, you require() the base class,
-just like in the `Normal Autoload`_ method, but instead of defining an
-__autoload() function, you do::
+SPL__ (Standard PHP Library) also allows autoloading to be set up through the
+`spl_autoload_register`__ function. In this case, you ``require`` the base
+class, just like in the `Normal Autoload`_ method, but instead of defining an
+``__autoload()`` function, you do::
<?php
spl_autoload_register( array( 'ezcBase', 'autoload' ) );
?>
-.. _spl_autoload_register: http://php.net/manual/en/function.spl-autoload-register.php
+This way, you can register additional autoload functions for your own
+application or additional libraries.
+__ http://php.net/spl
+__ http://php.net/manual/en/function.spl-autoload-register.php
Worth knowing
-------------
+In following, we present some additional information on Apache Zeta Components,
+which you should know when starting to work with the library.
+
Required extensions
~~~~~~~~~~~~~~~~~~~
-eZ Components require as few extensions by default. Required by all components
-are:
+Apache Zeta Components require as few extensions by default. Required by all
+components are:
- SPL_
- iconv_
@@ -317,30 +355,28 @@ actively remove these from your PHP inst
care about them.
Specific components may require additional extensions, for example the database
-related components (Database_, DatabaseSchema_, PersistentObject_) rely on
-PDO_ being available. The components documentation will give a hint, if
-special extensions are required. You can find a full overview in the
-documentation__.
-
-.. _Database: /s/Database
-.. _DatabaseSchema: /s/DatabaseSchema
-.. _PersistentObject: /s/PersistentObject
+related components (Database_, DatabaseSchema_, PersistentObject_) rely on PDO_
+being available. The components documentation will give a hint, if special
+extensions are required.
+
+.. _Database: http://zetac.org/Database
+.. _DatabaseSchema: http://zetac.org/DatabaseSchema
+.. _PersistentObject: http://zetac.org/PersistentObject
.. _PDO: http://php.net/pdo
-__ /zetacomponents/introduction/requirements
Some components provide different drivers, which use different extensions or
-external programs. You can choose one of these to make the component
-use the backend that you have available. An example is the Graph_ component,
-which can use different extensions to render graphics in different formats.
+external programs. You can choose one of these to make the component use the
+back end that you have available. An example is the Graph_ component, which can
+use different extensions to render graphics in different formats.
-.. _Graph: /s/Graph
+.. _Graph: http://zetac.org/Graph
Character encoding
~~~~~~~~~~~~~~~~~~
-If not stated otherwise in the documentation, eZ Components assumes that the
-data that you provide is `UTF-8`__ encoded. In the same way, the output and
-return values generated by each are UTF-8 encoded as well.
+If not stated otherwise in the documentation, Apache Zeta Components assume
+that the data that you provide is `UTF-8`__ encoded. In the same way, the
+output and return values generated by each are UTF-8 encoded as well.
If you need to work with data in different encodings, make sure to convert this
data to UTF-8 before handing it into any of the components.
@@ -348,25 +384,25 @@ data to UTF-8 before handing it into any
.. __: http://en.wikipedia.org/wiki/Utf-8
To perform binary safe operations, the iconv_ extension is used internally in
-eZ Components. As mentioned before, this extension is delivered with PHP and
-activated by default. We recommend that you use this extension also for
+Apache Zeta Components. As mentioned before, this extension is delivered with
+PHP and activated by default. We recommend that you use this extension also for
potential encoding conversions.
Some components allow you to work with different encodings than UTF-8. For
example, the Mail_ component can work with several different encodings in
parallel. Such exceptions of the rule are clearly marked in the documentation.
-.. _Mail: http://ezcomponents.org/s/Mail
+.. _Mail: http://zetac.org/Mail
Conclusion
----------
Now you have a working environment which lets you integrate the object oriented
-eZ Components for efficient application development with PHP 5.2.1. Besides
-using the eZ Components for developing your own mission-critical applications,
-you can as well take a look at the source code to see how eZ Systems makes use
-of the new PHP 5 features for object oriented programming within the eZ
-Components. Have a lot of fun!
+Apache Zeta Components for efficient application development with PHP 5.2.1.
+Besides using the Apache Zeta Components for developing your own
+mission-critical applications, you can as well take a look at the source code
+to see how Apache Zeta Components make use of the new PHP 5 features for object
+oriented programming. Have a lot of fun!
Resources
---------