Declarative Development Using Annotations In PHP

Declarative Development using Annotations in PHP Frank Kleine & Stephan Schmidt

Agenda
The Speakers
Basic Concept of Annotations
Annotations in Java
Annotations in PHP
Annotations in Stubbles
Usage examples
Defining your own annotations
Q&A

Frank Kleine
Working at 1&1 Internet Inc.
PHP since 2000
Stubbles Lead Developer
Co-author of "Exploring PHP"

Stephan Schmidt
Team Leader at 1&1 Internet Inc.
Contributor to the PHP Open Source Community since 2001
15 PEAR packages, 1 pecl extension
Author of „PHP Design Patters“ and co-author of several other PHP-related books
Speaker at various conferences since 2001

The audience?
Who is using PHP5?
Who is using object-oriented development?
Who is using PHP‘s reflection features?

Basic concept of Annotations
Add metadata to classes, methods, properties
Do not (directly) affect program semantics
Can be used by tools or libraries
Can be parameterized or simple marker annotations

Example scenarios
Marking classes/methods as accessible via a web service
Marking methods as unit test methods
Defining how an object should be persisted or serialized
Automating dependency injection

Annotations in Java 4
Doclets, similar to PHPDoc
Accessible via a Doclet API and a command line tool
Not only used for documentation purposes
Xdoclet for creation of EJBs and more

Annotations in Java 5
Also accessible at runtime
public @interface MyAnnotation { String myParam(); } @MyAnnotation(myParam="Foo") public class MyClass {}
Annotations are part of the language

Annotations in PHP
Is this the end of the session?
Annotations are not part of any PHP version.

Annotations in PHP (revisited)
Probably 90% of you used some kind of annotation
/** * My class * * @author The Stubbles Team * @see http://www.stubbles.net */ class MyClass {}

History of annotations in PHP
There was PHPDoc
There was PHPDoc
PHP 5 was released
Some frameworks accessed PHPDoc tags
Some frameworks started using some "specialized" doc comments

Specialized frameworks
Annotations embedded in DocBlocks
Allow you to use annotations supported by the framework.
No generic parser for annotations, but mostly some regexps
Not (easily) possible to include new annotations

Extended Reflection API
Provides access to PHPDoc comments
Used to get information about the types of parameters or properties
No real annotation support
http://instantsvc.toolslave.net/wiki/ExtendedReflectionAPI

PHP_Unit
class Calculator {
/**
* @assert (0, 0) == 0
* @assert (1, 0) == 1
* @assert (1, 1) == 2
*/
public function add($a, $b)
{
return $a + $b;
}
}

SCA/SDO
class MyApplication {
/**
* The stock quote service to use.
*
* @reference
* @binding.wsdl ../StockQuote/StockQuote.wsdl
*/
public $stock_quote;
...
}

More specialized Frameworks
Services_Webservice makes use of "pimped" PHPDoc comments to create WSDL
EZPDO uses annotations to ease object-relational mapping

Next step: Generic frameworks
Enable you to create your own annotations
Provide generic annotation parsers
Provide access to annotations at run-time
No common standard for annotations

PEAR::PHP_Annotation
Parser for generic DocBlocks and Java-style annotations
Provides mechanism for dependency injection
No public release, yet
First and last commit 4 months ago

Addendum
Supports Java-style annotations
Annotations are classes that extend class Annotation
Annotations are accessible via reflection classes that extend built-in reflection
http://code.google.com/p/addendum/

Stubbles
OOP PHP 5.2 framework
Package based
Provides generic annotation functionality
Eats its own dog food and uses annotations in various packages

Annotations in Stubbles
Persistence
Serializing objects to XML
Persisting objects in RDMBS
Security
Marking methods as callable via JSON-RPC
Marking methods callable from XSLT
Misc
Managing dependency injection

A Person POPO
class Person {
protected $id;
protected $name;
protected $age;
protected $role;
public function __construct($id, $name, $age, $role = 'user') {
$this->id = $id;
$this->name = $name;
$this->age = $age;
$this->role = $role;
}
public function getId() {
return $this->id;
}
... more getter methods for the other properties ...
}

Serializing to XML
// Create a serializer
$serializer = new stubXMLSerializer();
// XML in Stubbles is created via a streaming API
$writer = stubXMLStreamWriterFactory::createAsAvailable();
// Create and serialize the object
$user = new Person (1, 'schst', 33, 'admin');
$serializer->serialize($user, $writer);
echo writer->asXML();

The resulting XML
<?xml version="1.0" encoding="ISO-8859-1"?>
< Person >
< getId >1</ getId >
< getName >schst</ getName >
< getAge >33</ getAge >
< getRole >admin</ getRole >
</ Person >

XMLSerializer behaviour
All public methods without parameters are exported
Class and method names are used as tag names
But: The behavior can be changed by annotating the class.

XMLSerializer annotations
Changing the name of the root tag:
/** * A person * * @XMLTag(tagName="user") */ class Person { ... rest of the code ... }

Changing the name of other tags
/** * Get the name * * @XMLTag(tagName="realname") * @return string */ public function getName() { return $this->name; }

Using attributes instead of tags
/** * Get the id * * @XMLAttribute(attributeName="userId") * @return int */ public function getId() { return $this->id; }

Ignoring methods
/** * Get the age * * @XMLIgnore * @return int */ public function getAge() { return $this->age; }

The modified XML
<?xml version="1.0" encoding="ISO-8859-1"?>
< user userId="1" >
< realname >schst</ realname >
< role >admin</ role >
</ user >
tag names have been changed
id property is serialized as attribute
age is omitted

Features of XMLSerializer
Serializes (nearly) every data structure
Able to use ext/dom or ext/xmlwriter
Able to serialize public methods and properties
Provides annotations to "batch-process" methods and properties

Persistence: POPO revisited /** * @DBTable(name='persons') ‏ */ class Person extends stubAbstractPersistable { ... properties like in old version ... /** * @DBColumn(name='person_id', isPrimaryKey=true) ‏ */ public function getId() { return $this->id; } } /** * @DBColumn(name='name', defaultValue='') ‏ */ public function getName() { return $this->name; } /** * @DBColumn(name='age', defaultValue=0) ‏ */ public function getAge() { return $this->age; } ... more ge tte r and of course setter methods for the other properties ... }

Persistence: insert ... create the person with the data ... $person = new Person(); $person->setName('Frank Kleine'); $person->setAge(27); $person->setRole('admin'); ... get the connection ... $connection = stubDatabaseConnectionPool::getConnection(); ... get the serializer ... $serializer = stubDatabaseSerializer::getInstance($connection); ... and save to database ... $serializer->serialize($person); ... done: ... var_dump($person->getId()); ... displays int(1) ...

Persistence: select (find) ‏ ... create the person object ... $person = new Person(); $person->setId(1); ... get the connection ... $connection = stubDatabaseConnectionPool::getConnection(); ... get the finder ... $finder = stubDatabaseFinder::getInstance($connection); ... and retrieve data ... $finder->findByPrimaryKeys($person); ... done: ... var_dump($person->getAge()); ... displays int(27) ... or: $criterion = new stubEqualCriterion('age', 27); $persons = $finder->findByCriterion($criterion, 'Person'); ... $persons is now an array containing a list of Person objects all of age 27

Persistence: more features
Delete similarly to finder
Update works like insert
Very simple support for joins (needs more research) ‏
Independent of database: connection handle knows database type, correct query builder is selected

Persistence: going crazy /** * @DBTable(name='persons', type='InnoDB') ‏ */ class Person extends stubAbstractPersistable { ... properties like in old version ... /** * @DBColumn(name='person_id', isPrimaryKey=true, type='int', size=10, isUnsigned=true) ‏ */ public function getId() { return $this->id; } } /** * @DBColumn(name='name', defaultValue='', type='varchar', size=255, isNullable=false) ‏ */ public function getName() { return $this->name; } } $connection = stubDatabaseConnectionPool::getConnection(); $creator = stubDatabaseCreator::getInstance($connection); $creator->createTable('Person');

Accessing annotations in PHP
PHP's built-in reflection API:
$class = new ReflectionClass('Person'); echo $class->getName() . " "; foreach ($class->getMethods() as $method) { echo " -> " . $method->getName() . " "; } Person -> __construct -> getId -> getName -> ...

Accessing annotations in PHP
Stubbles' reflection API:
$class = new stubReflectionClass ('Person'); if ($class-> hasAnnotation ('XMLTag')) { $xmlTag = $class-> getAnnotation ('XMLTag'); print_r($xmlTag); } stubXMLTagAnnotation Object ( [tagName:protected] => user [elementTagName:protected] => [annotationName:protected] => XMLTag )

Stubbles' reflection
Provides drop-in replacements for all built-in reflection classes, that extend the built-in classes (for type safety)
Provides two additional methods:
hasAnnotation(string name)
getAnnotation(string name)
Annotations are objects

Creating annotations
Annotation classes must implement stubAnnotation interface
Annotations can extend abstract base class
Annotations should comply to naming scheme
Annotations may contain additional properties and methods

Example: CSV Export
/**
* A person
*
* @CSV(file="users.csv",
* delimeter=";")
*/
class Person {
...properties and methods ...
/**
* Get the id
*
* @CSVField
* @return int
*/
public function getId() {
return $this->id;
}
}

The @CSV Annotation
class stubCSVAnnotation
extends stubAbstractAnnotation
implements stubAnnotation {
}

Annotation parameters
Parameters can be set in three ways
Providing a public property with the same name as the parameter
Providing a public method with the same name as the parameter prefixed with set
Providing a magic __set() method

The @CSV Annotation
class stubCSVAnnotation
public $file ;
protected $delimeter;
public function setDelimeter($delim) {
$this->delimeter = $delim;
}
public function getDelimeter() {
return $this->delimeter;
}
}

Annotation parameter types
Strings (enclosed in " or ')
integers and doubles
true , false and null
PHP constants for configurable annotations
instances of stubReflectionClass ( clazz=Person.class )

Annotation targets
Annotations may be added to
Classes
Properties
Methods
Functions
Each annotation may restrict the possible targets

The @CSV Annotation
class stubCSVAnnotation extends stubAbstractAnnotation implements stubAnnotation {
public function getAnnotationTarget() {
return stubAnnotation::TARGET_CLASS;
}
}
Should only be added to classes
Parser will throw an exception on error

The @CSVField Annotation
class stubCSVFieldAnnotation
public function getAnnotationTarget() {
return stubAnnotation::TARGET_METHOD
| stubAnnotation::TARGET_PROPERTY;
}
}
Can be added to methods and properties

Implementing the CSV Writer
Accept any object
Check for @CSV annotation
Extract parameters from annotation
Traverse all methods and properties
Check for @CSVField annotation
Invoke the methods
Write line to file

The CSVWriter class
class CSVWriter {
public static function write($obj) {
$class = new stubReflectionClass(get_class($obj));
if (! $class->hasAnnotation('CSV') ) {
throw new Exception('Not suported');
}
$csv = $class->getAnnotation('CSV');
$fp = fopen( $csv->file , 'a');
$fields = array();
foreach ($class->getMethods() as $method) {

The CSVWriter class
if (! $method->hasAnnotation('CSVField') ) {
continue;
}
$fields[] = $method->invoke($obj);
}
$line = implode( $csv->getDelimeter() , $fields);
fwrite($fp, $line . " ");
fclose($fp);
}
}

Using the CSVWriter class
$user = new Person(1, 'schst', 33, 'admin');
CSVWriter::write($user);
users.csv:
1;schst;33
Pass any annotated object to the write() method:

Advances Features
Annotations are cached during and between the requests
Annotations can be modified at run-tim

Advanced features
Annotations may be interfaces that can be implemented in various ways:
/** * @XMLMethods [XMLMatcher] (pattern='/^get(.+)/') */ class Person { ... methods ... }

Annotation interfaces
XMLSerializer only knows about the @XMLMethods annotation interface
XMLMatcher implements this interface and decides which methods to export
Annotations do not only provide meta information, but also logic

The end
Thank you for your attention.
Want to know more?
http://www.stubbles.net
http://www.frankkleine.de
http://www.schst.net

Commercial break

http://phpbr.wordpress.com	1697
http://www.slideshare.net	64
http://www.stubbles.org	47
http://francescoagati.wordpress.com	40
http://stubbles.org	9
http://www.infoblogs.com.br	3
https://si0.twimg.com	3
http://static.slideshare.net	2
url_unknown	2
http://webcache.googleusercontent.com	2
http://localhost	1
https://s3.amazonaws.com	1
http://musarra.wordpress.com	1
http://paper.li	1
http://64.233.169.104	1
http://translate.googleusercontent.com	1

Declarative Development Using Annotations In PHP

by stubbles on May 22, 2007

Accessibility

Categories

Upload Details

Usage Rights

16 Embeds 1,875

Statistics

Declarative Development Using Annotations In PHP Presentation Transcript