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 je...@apache.org on 2011/07/10 17:31:24 UTC
[zeta-commits] svn commit: r1144915 [2/37] - in /incubator/zetacomponents:
trunk/Authentication/docs/ trunk/AuthenticationDatabaseTiein/docs/
trunk/Base/docs/ trunk/Configuration/docs/ trunk/Document/docs/
trunk/EventLog/docs/ trunk/Feed/docs/ trunk/File/docs/ trunk/...
Modified: incubator/zetacomponents/website/htdocs/community/dev_process.html
URL: http://svn.apache.org/viewvc/incubator/zetacomponents/website/htdocs/community/dev_process.html?rev=1144915&r1=1144914&r2=1144915&view=diff
==============================================================================
--- incubator/zetacomponents/website/htdocs/community/dev_process.html (original)
+++ incubator/zetacomponents/website/htdocs/community/dev_process.html Sun Jul 10 17:30:59 2011
@@ -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="jeromer" />
<meta name="language" content="en" />
- <meta name="date" content="Tue, 03 Aug 2010 10:23:50 +0200" />
+ <meta name="date" content="Wed, 06 Apr 2011 12:44:44 +0200" />
<meta name="robots" content="all" />
<link rel="schema.DC" href="http://purl.org/dc/elements/1.1/" />
<meta name="DC.title" content="Development process" />
- <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="jeromer" />
+ <meta name="DC.date" content="Wed, 06 Apr 2011 12:44:44 +0200" />
<meta name="DC.rights" content="Copyright" />
<link rel="meta" href="/zetacomponents/community/dev_process.rdf" />
@@ -71,7 +71,7 @@
<div class="content">
- <h2>Development Process</h2><div class="toc"><h3>Table of Contents</h3><ul><li><p><a href="#introduction">Introduction</a></p></li><li><p><a href="#the-seven-steps">The Seven Steps</a></p><ul><li><p><a href="#detailed-information-about-the-steps">Detailed Information about the Steps</a></p></li><li><p><a href="#applicability">Applicability</a></p></li></ul></li><li><p><a href="#justifications">Justifications</a></p></li><li><p><a href="#version-states">Version States</a></p></li><li><p><a href="#glossary">Glossary</a></p><ul><li><p><a href="#maintainer">maintainer</a></p></li><li><p><a href="#maintainers">maintainers</a></p></li></ul></li></ul></div><a name="introduction"></a><a name="id19"></a><h3>Introduction</h3><p>In order to streamline our development we have a specific set of guidelines that need to be followed. This document summarizes the steps and provides pointers to the relevant guidelines where that is relevant. This document is ultimately meant for the Apache
Zeta Components developers.</p><p>Our development process consists of a set of seven steps; transitions between the different states can be done when the criteria are matched that describe the finalization of each step. Depending on the situation not all seven steps are necessary (for example for bug fixes you don't need to write a Requirements Document or Design Specification as a bug is simply a feature that doesn't adhere to those documents).</p><a name="the-seven-steps"></a><a name="id20"></a><h3>The Seven Steps</h3><ol><li><p><a href="#present-the-idea">Present the Idea</a>.</p></li><li><p><a href="#write-requirements-document">Write Requirements Document</a>.</p></li><li><p>Write <a href="#design-specifications">Design Specifications</a>.</p></li><li><p><a href="#time-and-cost-estimates">Time and Cost Estimates</a>.</p></li><li><p><a href="#implementation">Implementation</a>.</p></li><li><p><a href="#testing">Testing</a>.</p></li><li><p><a href="#release">Release</a>.
</p></li></ol><a name="detailed-information-about-the-steps"></a><a name="id21"></a><h4>Detailed Information about the Steps</h4><a name="id1"></a><h5>1. <a name="present-the-idea"></a>Present the Idea</h5><a name="new-feature"></a><h6>1.1. New Feature</h6><p>Before the requirements documents and design specifications are written an idea for a <em>new</em> feature should be announced on the <a href="http://lists.ez.no/mailman/listinfo/components">components mailing list</a>. This is to make sure that only features are developed which fit into our global idea of "high quality components for web application development". Based on the ideas that are outlined on the list we will make a decision whether we are interested in making a new feature part of the Apache Zeta Components library.</p><a name="enhancement"></a><h6>1.2. Enhancement</h6><p>Feature requests should go to the <a href="https://issues.apache.org/jira/browse/ZETACOMP">issue tracker</a>.</p><a name="bug"></a><h6>1.3
. Bug</h6><p>Bug reports should go to the <a href="https://issues.apache.org/jira/browse/ZETACOMP">issue tracker</a>.</p><a name="transition"></a><h6>Transition</h6><p>While introducing a new feature or an enhancement the following information should be present:</p><ul><li><p>What is the feature about?</p></li><li><p>Which features will it provide?</p></li><li><p>A rationale why it should be part of the product.</p></li></ul><p>Those three elements will be checked against our policies of what features we are interested it. <em>This document does not yet exist.</em></p><p>For bug reports the information in the <a href="https://issues.apache.org/jira/browse/ZETACOMP">issue tracker</a> should be filled in.</p><a name="id2"></a><h5>2. <a name="write-requirements-document"></a>Write Requirements Document</h5><p>After a new feature or enhancement has been announced, discussed and approved it is time to start writing the requirements document. At this point we will create a directo
ry in the experimental directory in SVN where the documents can be stored while waiting for feedback (<a href="http://svn.ez.no/svn/ezcomponents/experimental">http://svn.ez.no/svn/ezcomponents/experimental</a>/<component>/design). At this same time <em>some</em> prototyping can be done as well there.</p><p>There is also more information on how to structure an <a href="http://svn.ez.no/svn/ezcomponents/docs/guidelines/requirements_doc.txt">requirements document</a>.</p><a name="discussions"></a><h6>Discussions</h6><p>The requirements document is most likely going to attract feedback. This is supposed to be a creative and iterative process which means that proceeding to the next phase should not commence before the documents have been approved as well.</p><p>Discussions about the requirements should be done on the <a href="http://lists.ez.no/mailman/listinfo/components">components mailing list</a>.</p><a name="id3"></a><h6>Transition</h6><p>When the Requirements Document
contains all the required information, and it has been approved by the product manager, the next step can start where a Design Document is written.</p><a name="id4"></a><h5>3. <a name="design-specifications"></a>Design specifications</h5><p>At this point we assign a mentor to the component. This mentor makes sure all the necessary steps and reviews are done correctly and keeps an eye on the design, working closely with the developer that makes the design.</p><p>The design specification describes how the feature is going to be implemented with the requirements document in mind. The design specification is there to see whether something can be implemented, and also explores the different implementation approaches. The different approaches can then be assessed in the next step (<a href="#time-and-cost-estimates">Time and Cost Estimates</a>).</p><p>Only after the design specification has been approved can be started with the implementation of the feature. There are guidelines o
n how to create such an <a href="http://svn.ez.no/svn/ezcomponents/docs/guidelines/design_doc.txt">design specification</a>.</p><a name="id5"></a><h6>Discussions</h6><p>The design specification is most likely going to attract feedback in the form of different implementation approaches or just general comments.</p><p>Discussions about the design should be done on the <a href="http://lists.ez.no/mailman/listinfo/components">components mailing list</a>, or where possible in face-to-face meetings with a summary to the mailing list.</p><a name="id6"></a><h6>Transition</h6><p>The design specification is checked against the guidelines on how to write such a document. There is also an assessment whether the feature can be implemented at all. The design specification should be vetted by the product manager before the next step can be taken.</p><a name="id7"></a><h5>4. <a name="time-and-cost-estimates"></a>Time and Cost Estimates</h5><p>Once the requirement specifications have been wr
itten and the design has been made, it is possible to estimate how much time the implementation of a specific item will take. During the two previous phases all possible ways of implementation are researched and there is knowledge about what the implementation of a new feature exactly will entail.</p><p>There are a couple of things that need to be taken into account, for example which part of the software is to be touched. Standalone small parts are easier to estimate then larger parts that touch many different corners of the software.</p><a name="id8"></a><h5>5. <a name="implementation"></a>Implementation</h5><p>In the implementation step the feature is implemented according to the design specifications. When this step is reached for a new feature, the appropriate directory structures can be moved from "<a href="http://svn.ez.no/svn/ezcomponents/experimental/">experimental</a>" to "<a href="http://svn.ez.no/svn/ezcomponents/trunk/">trunk</a>".</p><p>There are several sub-it
ems in this step:</p><a name="id9"></a><h6>5.1. <a name="write-api-stubs-with-parameter-documentation-and-descriptions"></a>Write API stubs with parameter documentation and descriptions</h6><p>This should serve as some prototyping to see how the design could work. As part of the API stubs you should already create the files with the classes and methods that you think your API needs, following the design that is outlined in the design document. To complete this phase there should be an example in the main classes` doc blocks and API documentation for each constant, variable, property and method. Of course during development some things might change. This first initial implementation of the stubs just serves as a little playground. It is important that <em>no</em> implementation code is written during this phase. Documentation of classes is done with the <a href="http://phpdoc.org">phpDocumentor</a> syntax. A <a href="http://svn.ez.no/svn/ezcomponents/docs/guidelines/implemen
tation.txt">small introduction</a> on how to use it for the Apache Zeta Components is available as well.</p><a name="id10"></a><h7>Transition</h7><p>After the API stubs are written and committed to SVN a mail should be send to the <a href="http://lists.ez.no/mailman/listinfo/components">components mailing list</a> to ask for feedback.</p><a name="write-test-cases"></a><h6>5.2. Write test cases</h6><p>Test cases are written for PHPUnit, see the documentation on how to <a href="http://svn.ez.no/svn/ezcomponents/docs/test_environment.txt">set-up the test environment</a>.</p><a name="initial-implementation"></a><h6>5.3. Initial Implementation</h6><p>There are many guidelines for implementing classes and methods. Please refer to the <a href="http://svn.ez.no/svn/ezcomponents/docs/guidelines/implementation.txt">guidelines</a>.</p><a name="id11"></a><h7>Transition</h7><p>After the first implementation has been done, alpha1 is released.</p><a name="id12"></a><h6>5.4. <a name="initia
l-implementation-review"></a>Initial Implementation Review</h6><p>After the implementation of the classes there is a review required of the implementation. The review should be done by at least two people that where <em>not</em> part in writing the code. The original author is of course free to do a review as well. During the review the implementation should be matched against the requirements specification and design document. On top of there a few extra things should be taken care of, which are described in the <a href="http://svn.ez.no/svn/ezcomponents/docs/guidelines/review.txt">review</a> document.</p><a name="updating-implementation-according-to-review"></a><h6>5.5. Updating Implementation according to review</h6><p>After the <a href="#initial-implementation-review">Initial Implementation Review</a> has been done, the original developer updates the implementation according to provided feedback. In case conflicting opinions exist the issues need to be discussed on the l
ist, in all other cases it is suggested to discuss all found issues on the list as well.</p><a name="id13"></a><h7>Transition</h7><p>Release a beta version of the component.</p><a name="implementation-review"></a><h6>5.6. Implementation Review</h6><p>The updated code is reviewed once again according to the <a href="http://svn.ez.no/svn/ezcomponents/docs/guidelines/review.txt">review</a> guidelines. If more issues arise go back to step 5.5.</p><a name="id14"></a><h6>Transition</h6><p>Once the implementation has been reviewed and all the comments of the reviewers have been integrated into the implementation a Release Candidate can be released.</p><a name="id15"></a><h5>6. <a name="testing"></a>Testing</h5><p>In the testing phase we run all the Apache Zeta Components tests as one big bunch, using all the different permutations of parameters that we support. At the moment this is a multitude of PHP versions and supported Databases, but other input variables might be defined late
r as well.</p><a name="id16"></a><h6>Transition</h6><p>Before we can do the release, we run a couple of scripts that validate a few basic things:</p><ul><li><p>whether we have uncommitted changes</p></li><li><p>whether all tests pass</p></li><li><p>whether line endings are correct</p></li><li><p>whether the ChangeLog parses correctly as reST file</p></li><li><p>code style guidelines are checked with a script</p></li></ul><a name="id17"></a><h5>7. <a name="release"></a>Release</h5><p>A document that describes how to make releases of the Apache Zeta Components can be found in <a href="http://svn.ez.no/svn/ezcomponents/docs/releasing.txt">svn</a>.</p><a name="applicability"></a><a name="id22"></a><h4>Applicability</h4><a name="new-features"></a><h5>New Features</h5><p>Should follow all of <a href="#the-seven-steps">The Seven Steps</a>.</p><a name="bugs"></a><h5>Bugs</h5><p>Bugs should should always be reported in the <a href="https://issues.apache.org/jira/browse/ZETACOMP">issu
e tracker</a>. Bugs should also be reported here by ourselves if we are not in the first development cycle of a component (e.g. before version 1.0) or during an active development face for a new .y release. This allows easier tracking of issues. While committing a bug fix the bug number should be mentioned.</p><p>For bugs from non-<a href="#maintainers">maintainers</a> that come with a patch, the patch should be reviewed by one of the maintainers of the specific area. The patch should be attached to the bug report and when updates of the patch are requested through the <a href="https://issues.apache.org/jira/browse/ZETACOMP">issue tracker</a> the non-<a href="#maintainer">maintainer</a> should update his patch there. All patches for bug reports have to include test cases that show that before the fix the bug failed, and afterwards it was fixed. Of course a bug fix should not break other tests (unless they were incorrect of course). A patch by a non-<a href="#maintainer">main
tainer</a> can only be committed when the <a href="http://ez.no/ezpublish/contributing/cla">CLA</a> has been signed.</p><p>From the <a href="#the-seven-steps">The Seven Steps</a>, step 2 (<a href="#write-requirements-document">Write Requirements Document</a>) and step 3 (Write <a href="#design-specifications">Design Specifications</a>) can be omitted because a bug is in violation with either one of those documents. Step 5.1 (<a href="#write-api-stubs-with-parameter-documentation-and-descriptions">Write API stubs with parameter documentation and descriptions</a>) and step 5.4/5.6 (<a href="#initial-implementation-review">Initial Implementation Review</a>) are also not required, although the latter might be a good idea to do for very large fixes.</p><a name="enhancements"></a><h5>Enhancements</h5><p>Should just like bugs always be filed into the <a href="https://issues.apache.org/jira/browse/ZETACOMP">issue tracker</a>, also if it comes from <a href="#maintainers">maintainers<
/a>. The development process is handled in the same way as new features. When an enhancement is filed, the specs of the feature/change are attached to the report in the issue tracker. Once the specification is approved by one or more of the current <a href="#maintainers">maintainers</a> and the product manager, it can be moved into the requirements and design documents. The development can be done in SVN directly, but is not required to be done there for non-<a href="#maintainers">maintainers</a>. Once a contributer has shown enough knowledge about a specific area he can be marked as a <a href="#maintainer">maintainer</a> for that specific area. Discussion about whether enhancements are wanted are always required to be done on the components mailing list. We can only allow code coming from external contributers into the repository when the <a href="http://ez.no/ezpublish/contributing/cla">CLA</a> has been signed.</p><a name="justifications"></a><a name="id23"></a><h3>Justifi
cations</h3><p>The process outlined above solves the basic requirement of accepting contributions while defining a clear process. The Components are self contained building blocks and therefore changes are often very small and contained. Because of this nature it is not required that every little issue is reviewed by at least one other person. By allowing direct commit access to SVN we allow quicker development while still maintaining quality (as every addition and bug fix is required to have a test case). Because the components have a quick release cycle we would hardly have conflicts between bug fixes and new features so we do not have to create many branches. A component would usually have one branch, or perhaps two concurrent ones if we go for a version 2 of a component. We are reluctant to bump the version number to 2 though as this would only be done on a backward compatibility breaking change.</p><a name="version-states"></a><a name="id24"></a><h3>Version States</h3><
dl><dt>pre-alpha</dt><dd>Development state, everything can change.</dd><dt>alpha 1</dt><dd>First release of a component up for initial review.</dd><dt>beta 1</dt><dd>First release of a component after the implementation of review comments. The API is still subject to change, but the general workings of the component should not change anymore.</dd><dt>beta n</dt><dd>Releases of a component after implementation of more reviews. The API is still allowed to change, but doing so is discouraged.</dd><dt>rc 1</dt><dd>Release candidate, the API can not change anymore unless there is an extremely compelling reason to do so.</dd><dt>final</dt><dd>The component is now released, BC can <em>not</em> be broken anymore.</dd></dl><a name="glossary"></a><a name="id25"></a><h3>Glossary</h3><a name="maintainer"></a><a name="id26"></a><h4>maintainer</h4><blockquote><p>A person from the Apache Zeta Components development team or an external contributer that has shown enough knowledge about a spe
cific component, or contributes a whole new component. Maintainers can commit directly to SVN.</p></blockquote><a name="maintainers"></a><a name="id27"></a><h4>maintainers</h4><blockquote><p>More than one <a href="#maintainer">maintainer</a>.</p></blockquote><!--Local Variables:-->
+ <h2>Development Process</h2><div class="toc"><h3>Table of Contents</h3><ul><li><p><a href="#introduction">Introduction</a></p></li><li><p><a href="#the-seven-steps">The Seven Steps</a></p><ul><li><p><a href="#detailed-information-about-the-steps">Detailed Information about the Steps</a></p></li><li><p><a href="#applicability">Applicability</a></p></li></ul></li><li><p><a href="#justifications">Justifications</a></p></li><li><p><a href="#version-states">Version States</a></p></li><li><p><a href="#glossary">Glossary</a></p><ul><li><p><a href="#maintainer">maintainer</a></p></li><li><p><a href="#maintainers">maintainers</a></p></li></ul></li></ul></div><a name="introduction"></a><a name="id19"></a><h3>Introduction</h3><p>In order to streamline our development we have a specific set of guidelines that need to be followed. This document summarizes the steps and provides pointers to the relevant guidelines where that is relevant. This document is ultimately meant for the Apache
Zeta Components developers.</p><p>Our development process consists of a set of seven steps; transitions between the different states can be done when the criteria are matched that describe the finalization of each step. Depending on the situation not all seven steps are necessary (for example for bug fixes you don't need to write a Requirements Document or Design Specification as a bug is simply a feature that doesn't adhere to those documents).</p><a name="the-seven-steps"></a><a name="id20"></a><h3>The Seven Steps</h3><ol><li><p><a href="#present-the-idea">Present the Idea</a>.</p></li><li><p><a href="#write-requirements-document">Write Requirements Document</a>.</p></li><li><p>Write <a href="#design-specifications">Design Specifications</a>.</p></li><li><p><a href="#time-and-cost-estimates">Time and Cost Estimates</a>.</p></li><li><p><a href="#implementation">Implementation</a>.</p></li><li><p><a href="#testing">Testing</a>.</p></li><li><p><a href="#release">Release</a>.
</p></li></ol><a name="detailed-information-about-the-steps"></a><a name="id21"></a><h4>Detailed Information about the Steps</h4><a name="id1"></a><h5>1. <a name="present-the-idea"></a>Present the Idea</h5><a name="new-feature"></a><h6>1.1. New Feature</h6><p>Before the requirements documents and design specifications are written an idea for a <em>new</em> feature should be announced on the <a href="http://lists.ez.no/mailman/listinfo/components">components mailing list</a>. This is to make sure that only features are developed which fit into our global idea of "high quality components for web application development". Based on the ideas that are outlined on the list we will make a decision whether we are interested in making a new feature part of the Apache Zeta Components library.</p><a name="enhancement"></a><h6>1.2. Enhancement</h6><p>Feature requests should go to the <a href="https://issues.apache.org/jira/browse/ZETACOMP">issue tracker</a>.</p><a name="bug"></a><h6>1.3
. Bug</h6><p>Bug reports should go to the <a href="https://issues.apache.org/jira/browse/ZETACOMP">issue tracker</a>.</p><a name="transition"></a><h6>Transition</h6><p>While introducing a new feature or an enhancement the following information should be present:</p><ul><li><p>What is the feature about?</p></li><li><p>Which features will it provide?</p></li><li><p>A rationale why it should be part of the product.</p></li></ul><p>Those three elements will be checked against our policies of what features we are interested it. <em>This document does not yet exist.</em></p><p>For bug reports the information in the <a href="https://issues.apache.org/jira/browse/ZETACOMP">issue tracker</a> should be filled in.</p><a name="id2"></a><h5>2. <a name="write-requirements-document"></a>Write Requirements Document</h5><p>After a new feature or enhancement has been announced, discussed and approved it is time to start writing the requirements document. At this point we will create a directo
ry in the experimental directory in SVN where the documents can be stored while waiting for feedback (<a href="http://svn.ez.no/svn/ezcomponents/experimental">http://svn.ez.no/svn/ezcomponents/experimental</a>/<component>/design). At this same time <em>some</em> prototyping can be done as well there.</p><p>There is also more information on how to structure an <a href="http://svn.ez.no/svn/ezcomponents/docs/guidelines/requirements_doc.txt">requirements document</a>.</p><a name="discussions"></a><h6>Discussions</h6><p>The requirements document is most likely going to attract feedback. This is supposed to be a creative and iterative process which means that proceeding to the next phase should not commence before the documents have been approved as well.</p><p>Discussions about the requirements should be done on the <a href="http://lists.ez.no/mailman/listinfo/components">components mailing list</a>.</p><a name="id3"></a><h6>Transition</h6><p>When the Requirements Document
contains all the required information, and it has been approved by the product manager, the next step can start where a Design Document is written.</p><a name="id4"></a><h5>3. <a name="design-specifications"></a>Design specifications</h5><p>At this point we assign a mentor to the component. This mentor makes sure all the necessary steps and reviews are done correctly and keeps an eye on the design, working closely with the developer that makes the design.</p><p>The design specification describes how the feature is going to be implemented with the requirements document in mind. The design specification is there to see whether something can be implemented, and also explores the different implementation approaches. The different approaches can then be assessed in the next step (<a href="#time-and-cost-estimates">Time and Cost Estimates</a>).</p><p>Only after the design specification has been approved can be started with the implementation of the feature. There are guidelines o
n how to create such an <a href="http://svn.ez.no/svn/ezcomponents/docs/guidelines/design_doc.txt">design specification</a>.</p><a name="id5"></a><h6>Discussions</h6><p>The design specification is most likely going to attract feedback in the form of different implementation approaches or just general comments.</p><p>Discussions about the design should be done on the <a href="http://lists.ez.no/mailman/listinfo/components">components mailing list</a>, or where possible in face-to-face meetings with a summary to the mailing list.</p><a name="id6"></a><h6>Transition</h6><p>The design specification is checked against the guidelines on how to write such a document. There is also an assessment whether the feature can be implemented at all. The design specification should be vetted by the product manager before the next step can be taken.</p><a name="id7"></a><h5>4. <a name="time-and-cost-estimates"></a>Time and Cost Estimates</h5><p>Once the requirement specifications have been wr
itten and the design has been made, it is possible to estimate how much time the implementation of a specific item will take. During the two previous phases all possible ways of implementation are researched and there is knowledge about what the implementation of a new feature exactly will entail.</p><p>There are a couple of things that need to be taken into account, for example which part of the software is to be touched. Standalone small parts are easier to estimate then larger parts that touch many different corners of the software.</p><a name="id8"></a><h5>5. <a name="implementation"></a>Implementation</h5><p>In the implementation step the feature is implemented according to the design specifications. When this step is reached for a new feature, the appropriate directory structures can be moved from "<a href="http://svn.ez.no/svn/ezcomponents/experimental/">experimental</a>" to "<a href="http://svn.ez.no/svn/ezcomponents/trunk/">trunk</a>".</p><p>There are several sub-it
ems in this step:</p><a name="id9"></a><h6>5.1. <a name="write-api-stubs-with-parameter-documentation-and-descriptions"></a>Write API stubs with parameter documentation and descriptions</h6><p>This should serve as some prototyping to see how the design could work. As part of the API stubs you should already create the files with the classes and methods that you think your API needs, following the design that is outlined in the design document. To complete this phase there should be an example in the main classes` doc blocks and API documentation for each constant, variable, property and method. Of course during development some things might change. This first initial implementation of the stubs just serves as a little playground. It is important that <em>no</em> implementation code is written during this phase. Documentation of classes is done with the <a href="http://phpdoc.org">phpDocumentor</a> syntax. A <a href="http://svn.ez.no/svn/ezcomponents/docs/guidelines/implemen
tation.txt">small introduction</a> on how to use it for the Apache Zeta Components is available as well.</p><a name="id10"></a><h7>Transition</h7><p>After the API stubs are written and committed to SVN a mail should be send to the <a href="http://lists.ez.no/mailman/listinfo/components">components mailing list</a> to ask for feedback.</p><a name="write-test-cases"></a><h6>5.2. Write test cases</h6><p>Test cases are written for PHPUnit, see the documentation on how to <a href="http://svn.ez.no/svn/ezcomponents/docs/test_environment.txt">set-up the test environment</a>.</p><a name="initial-implementation"></a><h6>5.3. Initial Implementation</h6><p>There are many guidelines for implementing classes and methods. Please refer to the <a href="http://svn.ez.no/svn/ezcomponents/docs/guidelines/implementation.txt">guidelines</a>.</p><a name="id11"></a><h7>Transition</h7><p>After the first implementation has been done, alpha1 is released.</p><a name="id12"></a><h6>5.4. <a name="initia
l-implementation-review"></a>Initial Implementation Review</h6><p>After the implementation of the classes there is a review required of the implementation. The review should be done by at least two people that where <em>not</em> part in writing the code. The original author is of course free to do a review as well. During the review the implementation should be matched against the requirements specification and design document. On top of there a few extra things should be taken care of, which are described in the <a href="http://svn.ez.no/svn/ezcomponents/docs/guidelines/review.txt">review</a> document.</p><a name="updating-implementation-according-to-review"></a><h6>5.5. Updating Implementation according to review</h6><p>After the <a href="#initial-implementation-review">Initial Implementation Review</a> has been done, the original developer updates the implementation according to provided feedback. In case conflicting opinions exist the issues need to be discussed on the l
ist, in all other cases it is suggested to discuss all found issues on the list as well.</p><a name="id13"></a><h7>Transition</h7><p>Release a beta version of the component.</p><a name="implementation-review"></a><h6>5.6. Implementation Review</h6><p>The updated code is reviewed once again according to the <a href="http://svn.ez.no/svn/ezcomponents/docs/guidelines/review.txt">review</a> guidelines. If more issues arise go back to step 5.5.</p><a name="id14"></a><h6>Transition</h6><p>Once the implementation has been reviewed and all the comments of the reviewers have been integrated into the implementation a Release Candidate can be released.</p><a name="id15"></a><h5>6. <a name="testing"></a>Testing</h5><p>In the testing phase we run all the Apache Zeta Components tests as one big bunch, using all the different permutations of parameters that we support. At the moment this is a multitude of PHP versions and supported Databases, but other input variables might be defined late
r as well.</p><a name="id16"></a><h6>Transition</h6><p>Before we can do the release, we run a couple of scripts that validate a few basic things:</p><ul><li><p>whether we have uncommitted changes</p></li><li><p>whether all tests pass</p></li><li><p>whether line endings are correct</p></li><li><p>whether the ChangeLog parses correctly as reST file</p></li><li><p>code style guidelines are checked with a script</p></li></ul><a name="id17"></a><h5>7. <a name="release"></a>Release</h5><p>A document that describes how to make releases of the Apache Zeta Components can be found in <a href="http://svn.ez.no/svn/ezcomponents/docs/releasing.txt">svn</a>.</p><a name="applicability"></a><a name="id22"></a><h4>Applicability</h4><a name="new-features"></a><h5>New Features</h5><p>Should follow all of <a href="#the-seven-steps">The Seven Steps</a>.</p><a name="bugs"></a><h5>Bugs</h5><p>Bugs should should always be reported in the <a href="https://issues.apache.org/jira/browse/ZETACOMP">issu
e tracker</a>. Bugs should also be reported here by ourselves if we are not in the first development cycle of a component (e.g. before version 1.0) or during an active development face for a new .y release. This allows easier tracking of issues. While committing a bug fix the bug number should be mentioned.</p><p>For bugs from non-<a href="#maintainers">maintainers</a> that come with a patch, the patch should be reviewed by one of the maintainers of the specific area. The patch should be attached to the bug report and when updates of the patch are requested through the <a href="https://issues.apache.org/jira/browse/ZETACOMP">issue tracker</a> the non-<a href="#maintainer">maintainer</a> should update his patch there. All patches for bug reports have to include test cases that show that before the fix the bug failed, and afterwards it was fixed. Of course a bug fix should not break other tests (unless they were incorrect of course). A patch by a non-<a href="#maintainer">main
tainer</a> can only be committed when the <a href="http://www.apache.org/licenses/">CLA</a> has been signed.</p><p>From the <a href="#the-seven-steps">The Seven Steps</a>, step 2 (<a href="#write-requirements-document">Write Requirements Document</a>) and step 3 (Write <a href="#design-specifications">Design Specifications</a>) can be omitted because a bug is in violation with either one of those documents. Step 5.1 (<a href="#write-api-stubs-with-parameter-documentation-and-descriptions">Write API stubs with parameter documentation and descriptions</a>) and step 5.4/5.6 (<a href="#initial-implementation-review">Initial Implementation Review</a>) are also not required, although the latter might be a good idea to do for very large fixes.</p><a name="enhancements"></a><h5>Enhancements</h5><p>Should just like bugs always be filed into the <a href="https://issues.apache.org/jira/browse/ZETACOMP">issue tracker</a>, also if it comes from <a href="#maintainers">maintainers</a>. The
development process is handled in the same way as new features. When an enhancement is filed, the specs of the feature/change are attached to the report in the issue tracker. Once the specification is approved by one or more of the current <a href="#maintainers">maintainers</a> and the product manager, it can be moved into the requirements and design documents. The development can be done in SVN directly, but is not required to be done there for non-<a href="#maintainers">maintainers</a>. Once a contributer has shown enough knowledge about a specific area he can be marked as a <a href="#maintainer">maintainer</a> for that specific area. Discussion about whether enhancements are wanted are always required to be done on the components mailing list. We can only allow code coming from external contributers into the repository when the <a href="http://www.apache.org/licenses/">CLA</a> has been signed.</p><a name="justifications"></a><a name="id23"></a><h3>Justifications</h3><p>T
he process outlined above solves the basic requirement of accepting contributions while defining a clear process. The Components are self contained building blocks and therefore changes are often very small and contained. Because of this nature it is not required that every little issue is reviewed by at least one other person. By allowing direct commit access to SVN we allow quicker development while still maintaining quality (as every addition and bug fix is required to have a test case). Because the components have a quick release cycle we would hardly have conflicts between bug fixes and new features so we do not have to create many branches. A component would usually have one branch, or perhaps two concurrent ones if we go for a version 2 of a component. We are reluctant to bump the version number to 2 though as this would only be done on a backward compatibility breaking change.</p><a name="version-states"></a><a name="id24"></a><h3>Version States</h3><dl><dt>pre-alpha
</dt><dd>Development state, everything can change.</dd><dt>alpha 1</dt><dd>First release of a component up for initial review.</dd><dt>beta 1</dt><dd>First release of a component after the implementation of review comments. The API is still subject to change, but the general workings of the component should not change anymore.</dd><dt>beta n</dt><dd>Releases of a component after implementation of more reviews. The API is still allowed to change, but doing so is discouraged.</dd><dt>rc 1</dt><dd>Release candidate, the API can not change anymore unless there is an extremely compelling reason to do so.</dd><dt>final</dt><dd>The component is now released, BC can <em>not</em> be broken anymore.</dd></dl><a name="glossary"></a><a name="id25"></a><h3>Glossary</h3><a name="maintainer"></a><a name="id26"></a><h4>maintainer</h4><blockquote><p>A person from the Apache Zeta Components development team or an external contributer that has shown enough knowledge about a specific component,
or contributes a whole new component. Maintainers can commit directly to SVN.</p></blockquote><a name="maintainers"></a><a name="id27"></a><h4>maintainers</h4><blockquote><p>More than one <a href="#maintainer">maintainer</a>.</p></blockquote><!--Local Variables:-->
<!--mode: rst-->
<!--fill-column: 79-->
<!--End:-->
Modified: incubator/zetacomponents/website/htdocs/community/dev_process.txt
URL: http://svn.apache.org/viewvc/incubator/zetacomponents/website/htdocs/community/dev_process.txt?rev=1144915&r1=1144914&r2=1144915&view=diff
==============================================================================
--- incubator/zetacomponents/website/htdocs/community/dev_process.txt (original)
+++ incubator/zetacomponents/website/htdocs/community/dev_process.txt Sun Jul 10 17:30:59 2011
@@ -325,7 +325,7 @@ Review`_) are also not required, althoug
to do for very large fixes.
-.. _CLA: http://ez.no/ezpublish/contributing/cla
+.. _CLA: http://www.apache.org/licenses/
Enhancements
~~~~~~~~~~~~
@@ -400,7 +400,7 @@ maintainers
-----------
More than one `maintainer`_.
-.. _`tutorial`: http://svn.ez.no/svn/ezcomponents/docs/guidelines/tutorial.txt
+.. _`tutorial`: https://svn.apache.org/repos/asf/incubator/zetacomponents/docs/guidelines/tutorial.txt
.. _`issue tracker`: https://issues.apache.org/jira/browse/ZETACOMP
Modified: incubator/zetacomponents/website/htdocs/documentation/trunk/Authentication.html
URL: http://svn.apache.org/viewvc/incubator/zetacomponents/website/htdocs/documentation/trunk/Authentication.html?rev=1144915&r1=1144914&r2=1144915&view=diff
==============================================================================
--- incubator/zetacomponents/website/htdocs/documentation/trunk/Authentication.html (original)
+++ incubator/zetacomponents/website/htdocs/documentation/trunk/Authentication.html Sun Jul 10 17:30:59 2011
@@ -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="dotxp" />
+ <meta name="author" content="jerome" />
<meta name="language" content="en" />
- <meta name="date" content="Wed, 04 Aug 2010 13:07:09 +0200" />
+ <meta name="date" content="Sun, 10 Jul 2011 11:10:40 +0200" />
<meta name="robots" content="all" />
<link rel="schema.DC" href="http://purl.org/dc/elements/1.1/" />
<meta name="DC.title" content="Authentication" />
- <meta name="DC.creator" content="dotxp" />
- <meta name="DC.date" content="Wed, 04 Aug 2010 13:07:09 +0200" />
+ <meta name="DC.creator" content="jerome" />
+ <meta name="DC.date" content="Sun, 10 Jul 2011 11:10:40 +0200" />
<meta name="DC.rights" content="Copyright" />
<link rel="meta" href="/zetacomponents/documentation/trunk/Authentication/tutorial.rdf" />
@@ -83,7 +83,7 @@
</ul>
- <h2>eZ Components - Authentication</h2><div class="toc"><h3>Table of Contents</h3><ul><li><p><a href="#introduction">Introduction</a></p><ul><li><p><a href="#description">Description</a></p></li></ul></li><li><p><a href="#class-overview">Class overview</a></p><ul><li><p><a href="#base-classes">Base classes</a></p></li><li><p><a href="#authentication-filters">Authentication filters</a></p></li><li><p><a href="#stores">Stores</a></p></li></ul></li><li><p><a href="#general-authentication">General authentication</a></p><ul><li><p><a href="#stateless-authentication">Stateless authentication</a></p></li><li><p><a href="#using-session">Using session</a></p><ul><li><p><a href="#improving-authentication-performance-when-using-the-session">Improving authentication performance when using the session</a></p></li></ul></li></ul></li><li><p><a href="#id1">Authentication filters</a></p><ul><li><p><a href="#database">Database</a></p></li><li><p><a href="#group">Group</a></p><ul><li><p><a
href="#multiple-credentials">Multiple credentials</a></p></li></ul></li><li><p><a href="#htpasswd">Htpasswd</a></p></li><li><p><a href="#ldap">LDAP</a></p><ul><li><p><a href="#fetch-extra-data-during-ldap-authentication">Fetch extra data during LDAP authentication</a></p></li></ul></li><li><p><a href="#openid">OpenID</a></p><ul><li><p><a href="#openid-dumb-stateless-mode">OpenID "dumb" (stateless) mode</a></p></li><li><p><a href="#openid-smart-stateful-mode">OpenID "smart" (stateful) mode</a></p></li><li><p><a href="#openid-immediate-mode">OpenID immediate mode</a></p></li><li><p><a href="#fetch-extra-data-during-openid-authentication">Fetch extra data during OpenID authentication</a></p></li><li><p><a href="#openid-2-0">OpenID 2.0</a></p></li></ul></li><li><p><a href="#token">Token</a></p></li><li><p><a href="#typekey">TypeKey</a></p><ul><li><p><a href="#fetch-extra-data-during-typekey-authentication">Fetch extra data during TypeKey authentication</a></p></li></ul></li></ul
></li><li><p><a href="#securing-applications">Securing applications</a></p></li></ul></div><a name="introduction"></a><a name="id3"></a><h3>Introduction</h3><a name="description"></a><a name="id4"></a><h4>Description</h4><p>The purpose of the Authentication component is to provide support for different means of identification and authentication of users using different providers and protocols.</p><a name="class-overview"></a><a name="id5"></a><h3>Class overview</h3><p>An overview of the most important classes in the Authentication component.</p><a name="base-classes"></a><a name="id6"></a><h4>Base classes</h4><dl><dt>ezcAuthentication</dt><dd>Main class of Authentication. It is a container for authentication filters, which will be run in sequence. The method run() returns true or false depending on the success of the authentication filters.</dd><dt>ezcAuthenticationCredentials</dt><dd>Structure which holds user credentials. Types are id credentials (<a href='/zetacomponents/
documentation/trunk/Authentication/phpdoc/ezcAuthenticationIdCredentials.html'>ezcAuthenticationIdCredentials</a>) and id + password credentials (<a href='/zetacomponents/documentation/trunk/Authentication/phpdoc/ezcAuthenticationPasswordCredentials.html'>ezcAuthenticationPasswordCredentials</a>). Usually there is only one credentials object in the application. Multiple credentials can be used via the <a href='/zetacomponents/documentation/trunk/Authentication/phpdoc/ezcAuthenticationGroupFilter.html'>ezcAuthenticationGroupFilter</a> class.</dd><dt>ezcAuthenticationSession</dt><dd>Used to store the authenticated username and the timestamp between requests.</dd></dl><a name="authentication-filters"></a><a name="id7"></a><h4>Authentication filters</h4><dl><dt>ezcAuthenticationDatabaseFilter</dt><dd>Filter to authenticate against a database. Uses a database instance provided by the Database component (via the <a href='/zetacomponents/documentation/trunk/Authentication/phpdoc/ez
cDbInstance.html#get'>ezcDbInstance::get</a>() function). It depends on the Database component, so it is implemented in the the tie-in component <a href="introduction_AuthenticationDatabaseTiein.html">AuthenticationDatabaseTiein</a>.</dd><dt>ezcAuthenticationGroupFilter</dt><dd>Container filter for 2 or more filters. Depending on configuration, at least one filter needs to succeed in order for the group to succeed, or all filters need to succeed in order for the group to succeed.</dd><dt>ezcAuthenticationHtpasswdFilter</dt><dd>Filter to authenticate against a htpasswd password file. Supports the same encryption methods as the Unix command htpasswd, and the encryption method is detected automatically from the file.</dd><dt>ezcAuthenticationLdapFilter</dt><dd>Filter to authenticate against an LDAP directory. For now the password can be only in plain text. It depends on the PHP ldap extension.</dd><dt>ezcAuthenticationOpenidFilter</dt><dd>Filter to authenticate against OpenID.
For now the OpenID versions 1.0 and 1.1 are supported.</dd><dt>ezcAuthenticationTokenFilter</dt><dd>Filter used to implement CAPTCHA tests. It basically compares the server generated token with the value entered by the user, using a specified hashing callback function.</dd></dl><a name="stores"></a><a name="id8"></a><h4>Stores</h4><p>OpenID uses a store to hold the generated nonces and the associations (in "smart" mode). If there is no store specified, then nonces are not checked.</p><dl><dt>ezcAuthenticationOpenidStore</dt><dd>Abstract class from which the different stores inherit.</dd><dt>ezcAuthenticationOpenidFileStore</dt><dd>Uses file storage. Nonces are stored in files named after the nonce itself, and associations are stored in files named after the OpenID provider with which the association is made.</dd><dt>ezcAuthenticationOpenidDbStore</dt><dd>Database storage. Nonces and associations are stored in two tables, with names defined as options in <a href='/zetacompone
nts/documentation/trunk/Authentication/phpdoc/ezcAuthenticationOpenidDbStoreOptions.html'>ezcAuthenticationOpenidDbStoreOptions</a>. Implemented in <a href="introduction_AuthenticationDatabaseTiein.html">AuthenticationDatabaseTiein</a>.</dd></dl><a name="general-authentication"></a><a name="id9"></a><h3>General authentication</h3><a name="stateless-authentication"></a><a name="id10"></a><h4>Stateless authentication</h4><p>The general template for authentication is:</p><ul><li><p>get the user credentials (eg. in a <a href='/zetacomponents/documentation/trunk/Authentication/phpdoc/ezcAuthenticationPasswordCredentials.html'>ezcAuthenticationPasswordCredentials</a> object)</p></li><li><p>create an object of class <a href='/zetacomponents/documentation/trunk/Authentication/phpdoc/ezcAuthentication.html'>ezcAuthentication</a> and pass the credentials object to it</p></li><li><p>add authentication filters to the authentication object with addFilter()</p></li><li><p>call the run() m
ethod of the authentication object</p></li><li><p>call the getStatus() method of the authentication object and analyse it</p></li></ul><p>The following example demonstrates the above steps.</p><ol class="code">
+ <h2>eZ Components - Authentication</h2><div class="toc"><h3>Table of Contents</h3><ul><li><p><a href="#introduction">Introduction</a></p><ul><li><p><a href="#description">Description</a></p></li></ul></li><li><p><a href="#class-overview">Class overview</a></p><ul><li><p><a href="#base-classes">Base classes</a></p></li><li><p><a href="#authentication-filters">Authentication filters</a></p></li><li><p><a href="#stores">Stores</a></p></li></ul></li><li><p><a href="#general-authentication">General authentication</a></p><ul><li><p><a href="#stateless-authentication">Stateless authentication</a></p></li><li><p><a href="#using-session">Using session</a></p><ul><li><p><a href="#improving-authentication-performance-when-using-the-session">Improving authentication performance when using the session</a></p></li></ul></li></ul></li><li><p><a href="#id1">Authentication filters</a></p><ul><li><p><a href="#database">Database</a></p></li><li><p><a href="#group">Group</a></p><ul><li><p><a
href="#multiple-credentials">Multiple credentials</a></p></li></ul></li><li><p><a href="#htpasswd">Htpasswd</a></p></li><li><p><a href="#ldap">LDAP</a></p><ul><li><p><a href="#fetch-extra-data-during-ldap-authentication">Fetch extra data during LDAP authentication</a></p></li></ul></li><li><p><a href="#openid">OpenID</a></p><ul><li><p><a href="#openid-dumb-stateless-mode">OpenID "dumb" (stateless) mode</a></p></li><li><p><a href="#openid-smart-stateful-mode">OpenID "smart" (stateful) mode</a></p></li><li><p><a href="#openid-immediate-mode">OpenID immediate mode</a></p></li><li><p><a href="#fetch-extra-data-during-openid-authentication">Fetch extra data during OpenID authentication</a></p></li><li><p><a href="#openid-2-0">OpenID 2.0</a></p></li></ul></li><li><p><a href="#token">Token</a></p></li><li><p><a href="#typekey">TypeKey</a></p><ul><li><p><a href="#fetch-extra-data-during-typekey-authentication">Fetch extra data during TypeKey authentication</a></p></li></ul></li></ul
></li><li><p><a href="#securing-applications">Securing applications</a></p></li></ul></div><a name="introduction"></a><a name="id3"></a><h3>Introduction</h3><a name="description"></a><a name="id4"></a><h4>Description</h4><p>The purpose of the Authentication component is to provide support for different means of identification and authentication of users using different providers and protocols.</p><a name="class-overview"></a><a name="id5"></a><h3>Class overview</h3><p>An overview of the most important classes in the Authentication component.</p><a name="base-classes"></a><a name="id6"></a><h4>Base classes</h4><dl><dt>ezcAuthentication</dt><dd>Main class of Authentication. It is a container for authentication filters, which will be run in sequence. The method run() returns true or false depending on the success of the authentication filters.</dd><dt>ezcAuthenticationCredentials</dt><dd>Structure which holds user credentials. Types are id credentials (<a href='/zetacomponents/
documentation/trunk/Authentication/phpdoc/ezcAuthenticationIdCredentials.html'>ezcAuthenticationIdCredentials</a>) and id + password credentials (<a href='/zetacomponents/documentation/trunk/Authentication/phpdoc/ezcAuthenticationPasswordCredentials.html'>ezcAuthenticationPasswordCredentials</a>). Usually there is only one credentials object in the application. Multiple credentials can be used via the <a href='/zetacomponents/documentation/trunk/Authentication/phpdoc/ezcAuthenticationGroupFilter.html'>ezcAuthenticationGroupFilter</a> class.</dd><dt>ezcAuthenticationSession</dt><dd>Used to store the authenticated username and the timestamp between requests.</dd></dl><a name="authentication-filters"></a><a name="id7"></a><h4>Authentication filters</h4><dl><dt>ezcAuthenticationDatabaseFilter</dt><dd>Filter to authenticate against a database. Uses a database instance provided by the Database component (via the <a href='/zetacomponents/documentation/trunk/Authentication/phpdoc/ez
cDbInstance.html#get'>ezcDbInstance::get</a>() function). It depends on the Database component, so it is implemented in the the tie-in component <a href="../AuthenticationDatabaseTiein/tutorial.html#introduction">AuthenticationDatabaseTiein</a>.</dd><dt>ezcAuthenticationGroupFilter</dt><dd>Container filter for 2 or more filters. Depending on configuration, at least one filter needs to succeed in order for the group to succeed, or all filters need to succeed in order for the group to succeed.</dd><dt>ezcAuthenticationHtpasswdFilter</dt><dd>Filter to authenticate against a htpasswd password file. Supports the same encryption methods as the Unix command htpasswd, and the encryption method is detected automatically from the file.</dd><dt>ezcAuthenticationLdapFilter</dt><dd>Filter to authenticate against an LDAP directory. For now the password can be only in plain text. It depends on the PHP ldap extension.</dd><dt>ezcAuthenticationOpenidFilter</dt><dd>Filter to authenticate agai
nst OpenID. For now the OpenID versions 1.0 and 1.1 are supported.</dd><dt>ezcAuthenticationTokenFilter</dt><dd>Filter used to implement CAPTCHA tests. It basically compares the server generated token with the value entered by the user, using a specified hashing callback function.</dd></dl><a name="stores"></a><a name="id8"></a><h4>Stores</h4><p>OpenID uses a store to hold the generated nonces and the associations (in "smart" mode). If there is no store specified, then nonces are not checked.</p><dl><dt>ezcAuthenticationOpenidStore</dt><dd>Abstract class from which the different stores inherit.</dd><dt>ezcAuthenticationOpenidFileStore</dt><dd>Uses file storage. Nonces are stored in files named after the nonce itself, and associations are stored in files named after the OpenID provider with which the association is made.</dd><dt>ezcAuthenticationOpenidDbStore</dt><dd>Database storage. Nonces and associations are stored in two tables, with names defined as options in <a href='
/zetacomponents/documentation/trunk/Authentication/phpdoc/ezcAuthenticationOpenidDbStoreOptions.html'>ezcAuthenticationOpenidDbStoreOptions</a>. Implemented in <a href="../AuthenticationDatabaseTiein/tutorial.html#introduction">AuthenticationDatabaseTiein</a>.</dd></dl><a name="general-authentication"></a><a name="id9"></a><h3>General authentication</h3><a name="stateless-authentication"></a><a name="id10"></a><h4>Stateless authentication</h4><p>The general template for authentication is:</p><ul><li><p>get the user credentials (eg. in a <a href='/zetacomponents/documentation/trunk/Authentication/phpdoc/ezcAuthenticationPasswordCredentials.html'>ezcAuthenticationPasswordCredentials</a> object)</p></li><li><p>create an object of class <a href='/zetacomponents/documentation/trunk/Authentication/phpdoc/ezcAuthentication.html'>ezcAuthentication</a> and pass the credentials object to it</p></li><li><p>add authentication filters to the authentication object with addFilter()</p></li
><li><p>call the run() method of the authentication object</p></li><li><p>call the getStatus() method of the authentication object and analyse it</p></li></ul><p>The following example demonstrates the above steps.</p><ol class="code">
<li><span style="color: #000000"><?php</span></li>
<li><span style="color: #0000FF">require_once </span><span style="color: #335533">'tutorial_autoload.php'</span><span style="color: #0000FF">;</span></li>
<li></li>
@@ -196,7 +196,7 @@
<li><span style="color: #007700"> // message that was created earlier)</span></li>
<li><span style="color: #0000FF">}</span></li>
<span style="color: #000000">?></span>
-</ol><p>In this way, the creation and initialization of the authentication filters is not performed if the credentials are stored in the session.</p><a name="id1"></a><a name="id13"></a><h3>Authentication filters</h3><a name="database"></a><a name="id14"></a><h4>Database</h4><p>See the <a href="introduction_AuthenticationDatabaseTiein.html">AuthenticationDatabaseTiein</a> component.</p><a name="group"></a><a name="id15"></a><h4>Group</h4><p>The following example shows how to use a group filter to authenticate against EITHER a database or an LDAP directory.</p><ol class="code">
+</ol><p>In this way, the creation and initialization of the authentication filters is not performed if the credentials are stored in the session.</p><a name="id1"></a><a name="id13"></a><h3>Authentication filters</h3><a name="database"></a><a name="id14"></a><h4>Database</h4><p>See the <a href="../AuthenticationDatabaseTiein/tutorial.html#introduction">AuthenticationDatabaseTiein</a> component.</p><a name="group"></a><a name="id15"></a><h4>Group</h4><p>The following example shows how to use a group filter to authenticate against EITHER a database or an LDAP directory.</p><ol class="code">
<li><span style="color: #000000"><?php</span></li>
<li><span style="color: #0000FF">require_once </span><span style="color: #335533">'tutorial_autoload.php'</span><span style="color: #0000FF">;</span></li>
<li></li>
@@ -525,7 +525,7 @@ $data = $filter->fetchData();</code><
<li><span style="color: #0000FF">}</span></li>
<li><span style="color: #000000">?></span></li>
-</ol><p>The only differences between this example and the one in the previous section is defining the mode of the OpenID filter, and defining a store (file store in this example or database store as shown in the OpenID example in <a href="introduction_AuthenticationDatabaseTiein.html">AuthenticationDatabaseTiein</a>) which will hold the associations. In addition the store will also hold the nonces which are used to prevent replay attacks.</p><p>The example also introduces the OpenID 2.0 version features, namely the possibility to use a common URL for all users of an OpenID provider (for example using <em>http://yahoo.com</em> in the login box), and then being redirected to the OpenID provider to enter the provider credentials, and in the end being redirected back with the unique user OpenID URL in the response from the OpenID provider (in the <strong>$url</strong> variable in the example above). See the section <a href="#openid-2-0">OpenID 2.0</a> below for more information.
</p><a name="openid-immediate-mode"></a><a name="id23"></a><h5>OpenID immediate mode</h5><p>The OpenID request checkid_immediate is supported, which allows for user authentication in a pop-up window or iframe (or similar techniques). Instead of redirecting the user agent as in the checkid_setup step, the developer has the possibility to open a pop-up/iframe for the user to authenticate with the OpenID provider.</p><p>A more detailed description of the process: when using checkid_immediate, the OpenID provider is asked if the user can be authenticated on the spot, with no redirection of the user agent. If the user cannot be authenticated, the provider sends back a setup URL, which the application can use in a pop-up window or iframe to display to the user so that he can authenticate himself to the OpenID provider. After user enters his OpenID username and password at this page and accepts the originating site, the pop-up window or iframe is redirected to the return URL value
(which should be a different page than the page which opens the pop-up window). The return URL page will then inform the main page of success or failure through JavaScript, and the main page can do the action that it needs to perform based on the outcome in the pop-up page.</p><p>The checkid_immediate mode is enabled by setting the option immediate to true.</p><p>Note: retrieval of extra data during authentication (fullname, email, etc) is not possible at the moment when using the immediate mode.</p><p>For example, this is one simple way of implementing checkid_immediate:</p><ul><li><p>the main page contains the OpenID login form (where the user types in his OpenID identifier). This page contains also a hidded form value which specifies to which page to return to in the pop-up window. The Enter key and the submit button should be disabled on the form. When user clicks on the Login button, the main page should employ AJAX to request the return URL. When the return URL finishe
s loading, the main page will read from the return URL page the setup URL and it will open it in a pop-up/iframe.</p></li><li><p>the return URL page enables the option immediate to the OpenID filter, and runs the filter. It gets back the setup URL and it echoes it to be picked-up by the main page once the return URL page will finish loading. The setup URL should be the only thing that the return URL page is echoing, to not interfere with the main page.</p></li><li><p>in the pop-up/iframe the setup URL will load, which basically depends on the OpenID provider how it is handled by the user. After the user enters his credentials on the setup URL page, he will be redirected to the return URL, which should detect this, and which should inform the main page that the user was authenticated to the OpenID provider.</p></li></ul><p>A rudimentary source code example is provided below. It does not contain code to inform the user that the session expired or the errors experienced during
the authentication process. The code has been tested on some browsers (Firefox 1.5, Konqueror 3.5, Internet Explorer 6.0), but it is possible that some browsers might have issues with the JavaScript code.</p><p>The main page:</p><ol class="code">
+</ol><p>The only differences between this example and the one in the previous section is defining the mode of the OpenID filter, and defining a store (file store in this example or database store as shown in the OpenID example in <a href="../AuthenticationDatabaseTiein/tutorial.html#introduction">AuthenticationDatabaseTiein</a>) which will hold the associations. In addition the store will also hold the nonces which are used to prevent replay attacks.</p><p>The example also introduces the OpenID 2.0 version features, namely the possibility to use a common URL for all users of an OpenID provider (for example using <em>http://yahoo.com</em> in the login box), and then being redirected to the OpenID provider to enter the provider credentials, and in the end being redirected back with the unique user OpenID URL in the response from the OpenID provider (in the <strong>$url</strong> variable in the example above). See the section <a href="#openid-2-0">OpenID 2.0</a> below for more
information.</p><a name="openid-immediate-mode"></a><a name="id23"></a><h5>OpenID immediate mode</h5><p>The OpenID request checkid_immediate is supported, which allows for user authentication in a pop-up window or iframe (or similar techniques). Instead of redirecting the user agent as in the checkid_setup step, the developer has the possibility to open a pop-up/iframe for the user to authenticate with the OpenID provider.</p><p>A more detailed description of the process: when using checkid_immediate, the OpenID provider is asked if the user can be authenticated on the spot, with no redirection of the user agent. If the user cannot be authenticated, the provider sends back a setup URL, which the application can use in a pop-up window or iframe to display to the user so that he can authenticate himself to the OpenID provider. After user enters his OpenID username and password at this page and accepts the originating site, the pop-up window or iframe is redirected to the retur
n URL value (which should be a different page than the page which opens the pop-up window). The return URL page will then inform the main page of success or failure through JavaScript, and the main page can do the action that it needs to perform based on the outcome in the pop-up page.</p><p>The checkid_immediate mode is enabled by setting the option immediate to true.</p><p>Note: retrieval of extra data during authentication (fullname, email, etc) is not possible at the moment when using the immediate mode.</p><p>For example, this is one simple way of implementing checkid_immediate:</p><ul><li><p>the main page contains the OpenID login form (where the user types in his OpenID identifier). This page contains also a hidded form value which specifies to which page to return to in the pop-up window. The Enter key and the submit button should be disabled on the form. When user clicks on the Login button, the main page should employ AJAX to request the return URL. When the return
URL finishes loading, the main page will read from the return URL page the setup URL and it will open it in a pop-up/iframe.</p></li><li><p>the return URL page enables the option immediate to the OpenID filter, and runs the filter. It gets back the setup URL and it echoes it to be picked-up by the main page once the return URL page will finish loading. The setup URL should be the only thing that the return URL page is echoing, to not interfere with the main page.</p></li><li><p>in the pop-up/iframe the setup URL will load, which basically depends on the OpenID provider how it is handled by the user. After the user enters his credentials on the setup URL page, he will be redirected to the return URL, which should detect this, and which should inform the main page that the user was authenticated to the OpenID provider.</p></li></ul><p>A rudimentary source code example is provided below. It does not contain code to inform the user that the session expired or the errors experie
nced during the authentication process. The code has been tested on some browsers (Firefox 1.5, Konqueror 3.5, Internet Explorer 6.0), but it is possible that some browsers might have issues with the JavaScript code.</p><p>The main page:</p><ol class="code">
<li><span style="color: #000000"><?php</span></li>
<li><span style="color: #0000FF">require_once </span><span style="color: #335533">'tutorial_autoload.php'</span><span style="color: #0000FF">;</span></li>
<li></li>
@@ -861,7 +861,7 @@ verisignlabs http://{username}.pip.veris
$data = $filter->fetchData();</code><p>The $data array will be something like this:</p><code class="block">array( 'name' => array( 'john' ),
'nick' => array( 'John Doe' ),
'email' => array( 'john.doe@example.com' ) // or not set
- );</code><a name="securing-applications"></a><a name="id29"></a><h3>Securing applications</h3><p><a href="Authentication_security.html">Securing applications</a> - A guide to improve the security of online applications. It is not exhaustive, but it provides solutions against common attacks.</p><!--Local Variables:
+ );</code><a name="securing-applications"></a><a name="id29"></a><h3>Securing applications</h3><p><a href="../Authentication/security.html">Securing applications</a> - A guide to improve the security of online applications. It is not exhaustive, but it provides solutions against common attacks.</p><!--Local Variables:
mode: rst
fill-column: 79
End: