Cómo crear Third party bundles de Symfony completamente extensibles y sobreescribibles

C
THIRD PARTY BUNDLES DE SYMFONY
COMPLETAMENTE EXTENSIBLES
Y SOBREESCRIBIBLES.

CÓMO CREAR THIRD PARTY BUNDLES DE SYMFONY COMPLETAMENTE EXTENSIBLES Y SOBREESCRIBIBLES
gerfignaedytebfodavegmiguelvilata
araquemario almacbe frankey90 driera_comraulo79

wolfwolker JL_Laso
araquemario almacbe frankey90 driera_comraulo79
gerfignaedytebfodavegmiguelvilata
paolacaracola

BEST PRACTICES FOR REUSABLE
BUNDLES

BEST PRACTICE # 1
NOMBRE DE LOS BUNDLES

AcmeBlogBundle

AcmeBundleBlogBundle

PSR4
Vendor(Category)*BundleName ~ Bundle
CamelCase
Descriptivo y corto
No más de dos palabras
NOMBRE DE LOS BUNDLES:

BEST PRACTICE # 2
ESTRUCTURA DE DIRECTORIOS

¿Qué ficheros y carpetas son obligados?

AcmeBlogBundle.php
README.(md | rst)
LICENSE
Resources/doc/index.rst
ESTRUCTURA DE LOS DIRECTORIOS:

Commands → Command/
Controllers → Controller/
Service Container Extensions → DependencyInjection/
Model classes → Model/
Configuration → Resources/config/
Web Resources (CSS, JS, images) → Resources/public/
Translation files → Resources/translations/
Templates → Resources/views/
Unit and Functional Tests → Tests/
ESTRUCTURA DE LOS DIRECTORIOS:

¿Cómo se tiene que llamar la carpeta
donde estén los Listeners y/o
Subscribers?

EventListener

El directorio de un bundle es de solo
lectura

Y si tu bundle necesita generar algún
fichero, ¿dónde lo crearías?

Solo si formarán parte del repositorio...

app/logs o app/cache

ContentController.php del Bundle
AcmeBlogBundle
¿directorio?

Acme/BlogBundle/Controller/ContentController.php

ContentController.php del Bundle
AcmeBlogBundle
¿FQC?

AcmeBlogBundleControllerContentController

SYMFONY CODING STANDARD
BEST PRACTICE # 4

class FooBar
{
const SOMECONST = 42;
/**
* @var string
*/
private $foo_bar;
private function transformText($dummy, array $options = array())
{
$defaultOptions = [
'some_default' => 'values',
'another_default' => 'more values'
];
foreach ($options as $option) {
if (!in_array($option, $defaultOptions)) {
throw new RuntimeException(sprintf('Unrecognized option "%s"', $option));
}
}
$mergedOptions = array_merge($defaultOptions,
$options
);
if (true === $dummy) {
return;
}
if ($dummy === 'string') {
if ('values' === $mergedOptions['some_default']) {
return substr($dummy, 0, 5);
}
return ucwords($dummy);
}
}
}

Sufijo Listener si escucha a algún evento

Clases Exception deben de ir en un
sub-space Exception

PHPUnit
Tests/
Los test funcionales solo deben testear la response y la
información de profiling si creas alguna.
No puede existir un test que sea AllTest.php
Tiene que haber un phpunit.xml.dist
TESTS

¿Cuánto % de cobertura tiene que
haber?

>= 95%

DOCUMENTACIÓN
BEST PRACTICE # 6

PHPDoc.
reStructuredText en Resources/doc/
DOCUMENTACIÓN:

INSTRUCCIONES DE INSTALACIÓN
README.md
Step 1: Download the Bundle
---------------------------
composer require blabla/blabla
Step 2: Enable the Bundle
-------------------------
Step 3, Step 4, etc. otros requisitos como registrar rutas...

¿Alias de AcmeBlogBundle?

acme_blog

Todas las rutas tiene que tener el alias
como prefijo

TRADUCCIONES
BEST PRACTICE # 8

¿formato recomendado yml, xliff, po ...?

XLIFF

XLIFF
Symfony Best Practices

¿Nombre del dominio de las
traducciones para AcmeBlogBundle?

acme_blog_domain

Un bundle NO tiene que sobreescribir
otros dominios de traducción

CONFIGURACIÓN
BEST PRACTICE # 9

Parámetros

# app/config/config.yml
parameters:
# @FrameworkBundle/Resources/config/translation.xml
translator.class: AcmeHelloBundleTranslationTranslator

Semantic bundle configuration

acme_social:
twitter:
client_id: 123
client_secret: $ecret

// src/Acme/SocialBundle/DependencyInjection/Configuration.php
namespace AcmeSocialBundleDependencyInjection;
use SymfonyComponentConfigDefinitionBuilderTreeBuilder;
use SymfonyComponentConfigDefinitionConfigurationInterface;
class Configuration implements ConfigurationInterface
{
public function getConfigTreeBuilder()
{
$treeBuilder = new TreeBuilder();
$rootNode = $treeBuilder->root('acme_social');
$rootNode
->children()
->arrayNode('twitter')
->children()
->integerNode('client_id')-> defaultValue(123123)->end()
->scalarNode('client_secret')-> defaultValue('k453jhdaj492')->end()
->end()
->end() // twitter
->end()
;
return $treeBuilder;
}
}

Semantic Versioning Standard.

MAJOR.MINOR.PATCH

¿Qué implicaciones tiene estar en la
versión 0.x.x?

“4 - Major version zero (0.y.z) is for initial
development. Anything may change at
any time. The public API should not be
considered stable.”

¿Cómo tiene que ser el id de los
servicios?

bundle_alias.service_id

¿Qué hacemos con los servicios que no
son usados por la aplicación si no
internamente en el bundle?

services:
foo:
class: ExampleFoo
public: false

¿Qué implica que un servicio sea
privado?

No se puede hacer: $container->get('foo');
Solo se puede inyectar en otro servicio en su definición.

¿Cómo vamos hasta aquí? ¿bien?

MECANISMOS DE SOBRE-
ESCRITURA Y HERENCIA

¿Cómo hacemos que un bundle herede
de otro?

Bundles
<?php
use SymfonyComponentHttpKernelBundleBundle;
class UserBundle extends Bundle
{
public function getParent()
{
return 'FOSUserBundle';
}
}

¿Qué implica esto?

Poder sobreescribir casi cualquier
archivo del bundle padre creándolo en
el mismo sitio que el padre.

CONTROLADORES
MECANISMOS... # 2

¿Cómo sobreescribimos el
comportamiento de un controlador?

Controladores
// src/UserBundle/Controller/RegistrationController.php
namespace UserBundleController;
use FOSUserBundleControllerRegistrationController as BaseController;
class RegistrationController extends BaseController
{
public function registerAction()
{
$response = parent::registerAction();
// ... do custom stuff
return $response;
}
}

¿Siempre que una ruta apunte a ese
action de ese controlador se llamará al
sobreescrito?

route_id:
path: /register
defaults: { _controller: FOSUserBundle:Registration:register }

¿De qué otra forma se puede hacer
referencia a un controlador?

UserBundleControllerRegistrationController::registerAction

route_id:
path: /register
defaults: { _controller:
UserBundleControllerRegistrationController::registerAction }

¿y otra forma?

¿se podría declarar como servicio un
controlador?

services:
fos_user.registration_controller:
class: FOSUserBundleControllerRegistrationController
...

route_id:
path: /register
defaults: { _controller: fos_user.registration_controller:registerAction }

route_id:
path: /register
defaults: { _controller: fos_user.registration_controller:registerAction }
Sí, pero de otra forma. Más adelante!

Por tanto, solo se sobreescribirá si se
usa ¿cómo?

FOSUserBundle:Registration:register

¿Cómo “encuentra” Symfony2 los
templates twig?

::index.html.twig

AcmeBlogBundle::index.html.twig

AcmeBlogBundle:Blog:index.html.twig

Orden de búsqueda
1. app/Resources/AcmeBlogBundle/views/layout.html.twig
2. src/Acme/BlogBundle/Resources/views/layout.html.twig
3. src/MyAcmeBlogBundle/Resources/views/layout.html.twig
- si fuera un bundle de vendors que hemos sobreescrito.
public function Bundle::getParent ( return ‘AcmeBlogBundle’; )
4. vendor/Acme/src/BlogBundle/Resources/views/layout.html.twig
- si fuera un bundle de vendors.

¿Qué dice Symfony Best Practices sobre
dónde tienen que ir los templates del
proyecto?

app/Resources

¿por qué?

“Routing is never automatically imported in
Symfony. If you want to include the routes from
any bundle, then they must be manually
imported from somewhere in your application
(e.g. app/config/routing.yml).”

“Copiar” las rutas del bundle y solo
importar y/o modificar las que se
deseen.

TRADUCCIONES
MECANISMOS... # 5

¿Qué son los dominios de las
traducciones?

$translator->trans('Symfony is great');

¿Cuál es el dominio de esa traducción?

messages.{lang}.{yml|po|xliff}

¿Cómo se selecciona el dominio en el
translator?

$translator->trans('label.is_valid', array(), 'SonataAdminBunde');
{{ 'label.is_valid'|trans({}, 'SonataAdminBundle') }}

La sobreescritura de traducciones
está relacionado con el dominio y no
con el bundle

WHAT?!

“The last translation file always wins...”
“Translation files are also not aware of
bundle inheritance...”

WTF?!

app/Resources/translations

VALIDACIONES
MECANISMOS... # 6

Grupos de validación

Grupo de Validación
class User implements UserInterface
{
/**
*
@AssertEmail(groups={"registration"})
*/
private $email;
/**
*
@AssertNotBlank(groups={"registration"})
* @AssertLength(min=7,
groups={"registration"})
*/
private $password;
/**
* @AssertValid()
*
@ORMOneToOne(targetEntity="Address"
, mappedBy="address")
*/
private $address;
/**
* @AssertLength(min=2)
*/
private $city;
}

class User implements UserInterface
{
/**
*
@AssertEmail(groups={"registration"})
*/
private $email;
/**
*
@AssertNotBlank(groups={"registration"})
* @AssertLength(min=7,
groups={"registration"})
*/
private $password;
/**
* @AssertValid()
*
@ORMOneToOne(targetEntity="Address"
, mappedBy="address")
*/
private $address;
/**
* @AssertLength(min=2)
*/
private $city;
}
Grupo de Validación

¿y cómo sobreescribimos las
validaciones?

“Symfony loads all validation
configuration files from every bundle and
combines them into one validation
metadata tree. This means you are able
to add new constraints to a property, but
you cannot override them.”

“To override this, the 3rd party bundle
needs to have configuration for validation
groups.”

Y…?

fos_user:
registration:
form:
validation_groups: [Registration, Default]

<service id="fos_user.registration.form.factory"
class="FOSUserBundleFormFactoryFormFactory">
<argument type="service" id="form.factory" />
<argument>%fos_user.registration.form.name%</argument>
<argument>%fos_user.registration.form.type%</argument>
<argument>%fos_user.registration.form.validation_groups%</argument>
</service>

$form = $this->createFormBuilder($users, array(
'validation_groups' => array('Registration', 'Default'),
))->add(...);

$errors = $validator
->validate($author, null, array('Registration', 'Default'));

1ª Sobreescribir parámetro de la clase
del servicio

2ª Sobreescribiendo el servicio creando
otro con el mismo id

2ª Sobreescribiendo el servicio creando
otro con el mismo id
Muy mala práctica

3ª Usando CompilerPass

¿Qué es un CompilerPass?

Es el modo en que Symfony2 permite
interactuar con los servicio y parámetros
definidos globalmente y en los bundles
cuando han sido cargados, pero antes
de que se hayan compilado y
optimizados en el DependencyInjection
Component (DIC)

original_service_id:
class: OriginalBundleServiceClass

// src/Acme/DemoBundle/DependencyInjection/Compiler/OverrideServiceCompilerPass.php
namespace AcmeDemoBundleDependencyInjectionCompiler;
use SymfonyComponentDependencyInjectionCompilerCompilerPassInterface;
use SymfonyComponentDependencyInjectionContainerBuilder;
class OverrideServiceCompilerPass implements CompilerPassInterface
{
public function process(ContainerBuilder $container)
{
$definition = $container->getDefinition('original-service-id');
$definition->setClass('AcmeDemoBundleYourService');
}
}

Declarado como servicio

services:
app.form.type.task:
class: AppBundleFormTypeTaskType
arguments: ["@app.my_service"]
tags:
- { name: form.type }

services:
app.form.type.task:
class: AppBundleFormTypeTaskType
arguments: ["@app.my_service"]
tags:
- { name: form.type }Como un servicio

Herencia de Forms

class GenderType extends AbstractType
{
...
public function getParent()
{
return ChoiceType::class;
}
}

¿Si queremos que un nuevo formulario
entre dentro del comportamiento del
bundle con alguna nueva funcionalidad?

El bundle tiene que proveer esa “lógica”
y permitir su configuración

¿Cómo?

fos_user:
registration:
form:
type: FOSUserBundleFormTypeRegistrationFormType

Form Type Extension

Form Type Extension
Documentación

¿MUCHA
INFORMACIÓN?

¿ABURRIDO?

¿SUEÑO?

TOMA AIRE ...

… RESPIRA ...

… Y PREPÁRATE ...

¡QUÉ VIENE LO COMPLICADO!

¡RELEVO!

ENTITIES &
ENTITY MAPPING

Due to the way Doctrine works, it is not
possible to override entity mapping of a
bundle. However, if a bundle provides a
mapped superclass (such as the User entity
in the FOSUserBundle) one can override
attributes and associations. Learn more
about this feature and its limitations in the
Doctrine documentation.
http://symfony.com/doc/current/cookbook/bundles/override.html#entities-entity-mapping

ENTITIES & ENTITY MAPPING # 1
CONCEPTOS BASE

ORM:
Object-Relational Mapping

ORM
≠
Active Record

Tenemos que dar doctrine la
información de “mapping”

MAPPING FORMATS

XML:
<field name="name" type="string" length=100 />

YML:
fields:
name:
type: string
length: 100

PHP:
$classMetadata ->mapField(array(
'fieldName' => 'slug',
'type' => 'string',
'nullable' => true
));

Annotations:
/**
* @ORMColumn(type="string", length=100)
*/
protected $name;

AUTOMAPPING

Automapping:
Busca información de mapeo:
● 1º ./Resources/config/doctrine/entityname. [xml | yml | php]
● 2º Annotation en ./Entity

En un bundle no se pueden mezclar
formatos
(annotation, xml, yml)

Automapping:
Funciona sólo si tengo una única
conexión a BD

# Doctrine Configuration
doctrine:
dbal:
driver: "%database_driver%"
host: "%database_host%"
port: "%database_port%"
dbname: "%database_name%"
user: "%database_user%"
password: "%database_password%"
charset: UTF8
orm:
auto_generate_proxy_classes: "%kernel.debug%"
default_entity_manager: default
entity_managers:
default:
auto_mapping: true
mappings:
AppBundle:
type: xml
dir: SomeResources/config/doctrine
http://symfony.com/doc/current/reference/configuration/doctrine.html

INHERITANCE MAPPING

Mapped Superclass:
No es una entidad, pero participa de alguna manera en el
árbol de herencia de clases

Mapped Superclass:
Su objetivo es definir información de mapeo que van a
heredar otras entidades

Mapped Superclass:
<mapped-superclass name="FOSUserBundleEntityUser">
<field name="username" column="username" type="string" length="255" />
….

Table Inheritance
Herencia de clases reflejada en base de datos

1 - Single Table Inheritance
/**
* @Entity
* @InheritanceType("SINGLE_TABLE")
* @DiscriminatorColumn(name="discr", type="string")
* @DiscriminatorMap({"person" = "Person", "employee" = "Employee"})
*/
class Person
{
// ...
}
/**
* @Entity
*/
class Employee extends Person
{
// ...
}

1 - Single Table Inheritance
/**
* @Entity
* @InheritanceType("SINGLE_TABLE")
*/
class Person
{
// ...
}
/**
* @Entity
*/
{
// ...
}
CUIDADO CON LOS CAMPOS NO NULLABLES

2 - Class Table Inheritance
/**
* @Entity
* @InheritanceType("JOINED")
*/
class Person
{
// ...
}
/**
* @Entity
*/
{
// ...
}

2 - Class Table Inheritance
/**
* @Entity
* @InheritanceType("JOINED")
*/
class Person
{
// ...
}
/**
* @Entity
*/
{
// ...
}
PERFORMANCE IMPACT

DYNAMIC MAPPING

Bind mapping files and classes
#AcmeMyBundle.php
private function buildMappingCompilerPass ()
{
$arguments = array(
array( realpath (__DIR__ . '/Resources/config/doctrine-base' )),
'.orm.xml'
);
$locator = new Definition ('DoctrineCommonPersistenceMappingDriverDefaultFileLocator' , $arguments );
$driver = new Definition ('DoctrineORMMappingDriverXmlDriver' , array( $locator ));
return new DoctrineOrmMappingsPass ($driver, array(
'FullNamespace'
) , array(
'your_bundle.manager_name'
) , 'your_bundle.orm_enabled' );
}
How to Provide Model Classes for several Doctrine Implementations (link)

loadClassMetadata event
# Acme/MyBundle/EventLister/MyMapper.php
public function loadClassMetadata(LoadClassMetadataEventArgs $eventArgs)
{
$classMetadata = $eventArgs->getClassMetadata();
if (null === $classMetadata->reflClass) {
return;
}
if ($this->isTimestampable($classMetadata)) {
if ($this->getClassAnalyzer()->hasMethod($classMetadata->reflClass, 'updateTimestamps')) {
$classMetadata->addLifecycleCallback('updateTimestamps', Events::prePersist);
$classMetadata->addLifecycleCallback('updateTimestamps', Events::preUpdate);
}
foreach (array('createdAt', 'updatedAt') as $field) {
if (!$classMetadata->hasField($field)) {
$classMetadata->mapField(array(
'fieldName' => $field,
'type' => $this->dbFieldType,
'nullable' => true
));
}
}
}
}

Sonata Doctrine Collector (EasyExtendsBundle)
/**
* @param array $config
*
* @throws Exception
*/
protected function addDoctrineDiscriminators(array $config)
{
$collector = DoctrineCollector::getInstance();
$purchasableClass = 'ReusableBundleEntityAbstractsAbstractPurchasable';
$collector->addDiscriminator($purchasableClass, 'PRODUCT', $config['class']['product']);
$types = $config['class']['purchasable_mapping'];
foreach ($types as $type) {
list($key, $class) = array_values($type);
if (!class_exists($class)) {
throw new Exception(sprintf('Class %s not found', $class));
}
//Add custom type
$collector->addDiscriminator($purchasableClass, $key, $class);
}
}

Relationships with abstract
classes and interfaces
<?xml version="1.0" encoding="UTF-8"?>
<doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"...>
<mapped-superclass name="ReusableBundleEntityAbstractsAbstractCartLine">
<id name="id" type="integer" column="id">
<generator strategy="AUTO"/>
</id>
<field name="quantity" column="quantity" type="integer" nullable="false" />
<many-to-one target-entity="ReusableBundleEntityAbstractsAbstractPurchasable"
field="purchasable" />
<many-to-one target-entity="ReusableBundleModelInterfacesCartInterface"
inversed-by="cartLines" field="cart" />
</mapped-superclass>
</doctrine-mapping>

Relationships with abstract
classes and interfaces
doctrine:
# ...
orm:
# ...
resolve_target_entities:
AcmeReusableBundleModelInterfacesCartInterface: AcmeAppBundleEntityCart

PUTTING ALL TOGETHER

Via MappedSuperClass
ENTITIES & ENTITY MAPPING # 6.1

FOSUserBundle
Sonata * Bundle
The bundle provides base classes which are already mapped for most fields to make it easier to
create your entity. Here is how you use it:
1. Extend the base User class
2. Map the id field. It must be protected as it is inherited from the parent class.
When you extend from the mapped superclass provided by the bundle, don't redefine the mapping
for the other fields as it is provided by the bundle.

FOSUserBundle
Sonata * Bundle
FOSUser no crea las relaciones entre
User - Group
Las deja del lado del cliente

via configuration
ENTITIES & ENTITY MAPPING
#
6.2

simple shopping cart
Cart
- user
- createdAt
- ...
CartLine
- cart
- purchasable
- quantity
- ...
Purchasable
- name
- price
- ...
Product
- media
- size
- ...
Ticket
- date
- ...
Book
- isbn
- ...
DeliverableTrait
- width
- height
- weight

Estrategia
Declarar clases abstractas y
mapearlas como mapped-super-class

Estrategia
Declarar una interfaz para cada clase

Estrategia
Heredar de la clase abstracta
evitando auto-mapping

Estrategia
Hacer configurable
acme_reusable:
class:
product: AppBundleEntityProduct
cart: ...
cart_line: ...
purchasables:
ticket: { key: TICKET, class: AppBundleEntityTickets }
book: { key: BOOK, class: AppBundleEntityBook }

Estrategia
// AcmeReusableExtension.php
protected function setConfiguration(ContainerBuilder $container, $config)
{
$container->setParameter('acme_reusable.model_manager_name', $config['model_manager_name']);
$container->setParameter('acme_reusable.orm_enabled', $config['orm_enabled']);
$this->configureClass($container, $config);
}

Estrategia
public function getConfigTreeBuilder()
{
$treeBuilder = new TreeBuilder();
$treeBuilder->root('acme_reusable')
->children()
->arrayNode('class')
->children()
->scalarNode('product')->cannotBeEmpty()->defaultValue(self::PRODUCT_CLASS)->end()
->scalarNode('cart')->cannotBeEmpty()->defaultValue(self::CART_CLASS)->end()
….
->arrayNode('purchasable_mapping')
->prototype('array')
->children()
->scalarNode('key')->end()
->scalarNode('class')->end()
->end()
->end()
->end()
->end()
->end()
->end()
->end();
return $treeBuilder;
}

Estrategia
// AcmeReusableBundle.php
private function buildOrmCompilerPass(ContainerBuilder $container)
{
$arguments = array(array(realpath(__DIR__.'/Resources/config/doctrine-model')), '.orm.xml');
$locator = new Definition('DoctrineCommonPersistenceMappingDriverDefaultFileLocator', $arguments);
$driver = new Definition('DoctrineORMMappingDriverXmlDriver', array($locator));
foreach ($this->getContainerExtension()->getEntitiesOverrides() as $configKey => $entity) {
$container->addCompilerPass(
new DoctrineOrmMappingsPass(
$driver,
array("%acme_reusable.$configKey.class%"),
array('acme_reusable.model_manager_name', 'orm'),
"acme_reusable.use_default.$configKey"
)
);
}
}

Estrategia
// AcmeReusableBundle.php
public function loadClassMetadata(LoadClassMetadataEventArgs $eventArgs)
{
$this->classMetadata = $eventArgs->getClassMetadata();
$classMetadata = $this->classMetadata;
if ($classMetadata->reflClass === $this->cartClass) {
$classMetadata->mapOneToMany(array(
'fieldName' => 'cartLines',
'targetEntity' => $this->cartLineClass,
'cascade' => array(
1 => 'all',
),
'mappedBy' => 'cart',
'orphanRemoval' => true,
));
}
}

Un ejemplo
https://github.com/gerfigna/ReusableBundle
https://github.com/gerfigna/DummyApp

Alfonso Machado
email@alfonsomachado.com
almacbe
Germán Figna
gfigna@gmail.com
gerfigna

Cómo crear Third party bundles de Symfony completamente extensibles y sobreescribibles

Recommended

Recommended

More Related Content

Recently uploaded

Recently uploaded (20)

Featured

Featured (20)

Cómo crear Third party bundles de Symfony completamente extensibles y sobreescribibles