Articles

Use annotations in your PHP Application to define Reusable Components with Ding

Tweet

Designing your PHP Application with components

Everything shown here using annotations, is also available by using the XML and YAML bean definition providers, so you are free to use any of the 3 drivers (XML, YAML, Annotations) to define your beans and mix them anyway you like or need to. See the dependency injection container manual for details on how to use xml and yaml.

One more thing :) These annotations are used to define the components, the annotations that are specifically designed to describe the component's injections and dependencies are described in "Ding annotations for dependency injection", so this one wont get too long.

Using the annotations @Component and @Named to Define your PHP Components

These annotations define beans (components). @Component comes from the Spring Framework and @Named from the JSR-330. Both are equivalent, and the reason to have both, is just to make it a little more comfortable for people that used one or the other. Ding is all about beans, which are components. There are types (not stereotypes, yet) for these components. So a basic generic component is defined with @Component or @Named (see below), and other components are specifically defined as of a given kind, like @Aspect, @Controller, @Configuration, @Controller, @Bean. So when an annotation defines a component, it will extend the definition of @Component, inheriting its options and available extra annotations.

Arguments

• name: A string or array of strings. Optional. Specifies a given name for the bean, and its aliases.
• primary: A boolean. Optional. If "true", when injecting by type (like @Inject) this will tell the container to choose this bean when multiple candidates are available. "false" by default.

Examples

Here he have a named component, with 3 names:

And here's one without a specific name, so Ding will autogenerate one:

Use @Primary to tag your PHP component as the best option with multiple ones can be chosen

This annotation is the equivalent of using "primary=true" in a bean/component definition.

Examples

Create Configuration classes for your PHP Application with the annotation @Configuration

This annotation lets you define beans that are the source for other bean definitions.

Arguments

This annotation extends the @Component definition. See @Component for the available options.

Examples

In this case, this class is the source for the bean definition of the bean "beanName". When this bean is requested, the method acts as a factory method for it (i.e: it gets called).

Create components from your PHP classes with @Bean

This annotation can be used in any method(s) inside any classes annotated as a component (like @Configuration, @Component, @Named, @Aspect, @Controller, etc), it will tell the container to use that particular component as a factory bean of the given bean name. @Bean methods accepts every annotation that a @Component accepts, like @Scope, @Singleton, @Prototype, @ListensOn, etc. If the argument "name" is omitted, the name of the bean is the name of the annotated method (i.e: the "name" argument will override it if present).

Arguments

This annotation extends the @Component definition. See @Component for the available options.

• class: A string. Optional. Since PHP is not strict about the types returned and the funcions/methods do not specify a type for the return value, this will tell the container that this particular bean is of type "class". When not specified, the bean will be of class StdClass.

Examples

In this case, this component is the source for the bean definition of the bean "beanName". When this bean is requested, the method acts as a factory method for it (i.e: it gets called).

@Scope

Use this annotation to define the bean scope, at the class level. Can also be used in @Bean methods.

Arguments

• value: A string, can be "singleton" or "prototype". Required.

Examples

Use the annotations @Singleton and @Prototype to define singletons in your PHP Application

@Singleton is equivalent to @Scope(value="singleton"), and @Prototype is equivalent to @Scope(value="prototype"). Can be used at the class level and in @Bean methods.

Examples

Define specific PHP methods with @InitMethod and @DestroyMethod so they are run on construct and destruct

These annotations lets you hook a method call right after the bean as been completely assembled (@InitMethod) and right before destructing it (@DestroyMethod). These are used at the class level, but can also be used in @Bean methods.

Arguments

• method: A string. Required. This is where the name of the method intended to be called is defined.

Examples

Use the annotations @PostConstruct and @PreDestroy to execute code during the lifecycle of your PHP Components

These annotations are used at the method level in @Component's, and are the equivalent of using @InitMethod(method="xxx") and @DestroyMethod(method="yyy") respectively. The main difference is that the latter are used at the class level and @PostConstruct and @PreDestroy are used at the method level, so you can't use them in @Bean methods.

Examples

Listening for events in your PHP Components with @ListensOn

This annotation tells ding that the given bean will listen for the specified event names. Can be used at the class level and in @Bean methods.

When one of the events is dispatched through the container (let's say event1 as an example), ding will try to find a method named onEvent1(). The event data will be sent as an argument. See the manual for details on using event driven programming with ding.

Arguments

• value: A string or an array of strings. Required. Specifies the name of the events that this bean will receive.

Examples