Download the PHP package optimeconsulting/sf-utils without Composer

SF Utils

Repo con clases de utilidad para proyectos Symfony >= 5

Instalación

Configuración

Agregar como un bundle en el config/bundles.php:

Configuración de opciones:

Crear/Ajustar el archivo config/packages/optime_utils.yaml:

Configuración adicional para usar traducciones de entidades

IMPORTANTE tener en cuenta que para la fecha (Mayo-2024) estas extensiones de doctrine no funcionan bien con doctrine >= 3.0, se debe usar 2.x.

Se debe instalar la libreria https://symfony.com/bundles/StofDoctrineExtensionsBundle/current/installation.html

Configurar la extension de traducciones:

config/packages/doctrine.yaml

config/packages/stof_doctrine_extensions.yaml

Uso

Optime\Util\Exception\DomainException

Clase para cuando se necesitan lanzar excepciones de dominio, es decir, excepciones que serán capturadas y controladas como parte del flujo de un proceso Errores de negocio (aprobar algo ya aprobado, rechazar algo que no se puede rechazar, salgo insuficiente, etc).

Optime\Util\Exception\ValidationException

Clase para cuando se necesitan lanzar excepciones de validación de dominio, es decir, errores de datos al ejecutar procesos de negocio (formato de un string, valor vacio, etc).

Esta clase es util por ejemplo para convertir la exception en un error de un formulario de Symfony:

Optime\Util\Batch\BatchProcessingResult

Clase de utilidad que sirve para obtener información del resultado de un proceso por lotes. Por ejemplo al cargar un CSV, podemos reflejar en dicha clase los elementos procesados correctamente y los que tuvieron algún problema de procesamiento.

Optime\Util\Validator\DomainValidator

Clase que usa el validador de Symfony y permite facilitar la integración del validador de Symfony con las Excepciones de Dominio de esta libreria. Puede lanzar un ValidationException si hay errores de validación.

Optime\Util\TranslatableMessage

Clase de utilidad que permite definir un mensaje traducible. Es usada por las Excepciones de Dominio de esta libreria. Ejemplo:

Traducciones en formularios:

Hay ciertas clases de utilidad para trabajar con campos traducibles, enfocado a la extensión de traducción de Doctrine pero que puede usarse de forma generica.

Importante

Para usar las traducciones en entidades, este bundle requiere de las extensiones de doctrine, especificamente la de traducciones, para ello instalar y seguir la documentación del bundle StofDoctrineExtensionsBundle.

Clases implicadas:

Optime\Util\Translation\TranslationsAwareInterface

Esta interfaz debe ser implementada por toda entidad y objeto que contenga y quiera manejar propiedades traducibles. Se deben implementar dos métodos para obtener o establecer el locale con el que se cargó la entidad o el objeto desde la fuente de datos.

La idea es que esta interfaz va a manejar el atributo en clase que contiene la anotación @Gedmo\Locale. Ver documentación del atributo del locale acá.

Se puede simplificar la implementación de la interfaz usando el Trait TranslationsAwareTrait:

Con el trait y se incorporan los métodos de la interfaz y el atributo con la anotación @Gedmo\Locale.

Optime\Util\Translation\TranslatableContent

Esta clase es un objeto "value object" que contiene un arreglo con un texto en distintos idiomas, cada indice del arreglo es un locale y su valor es el texto en dicho locale.

Optime\Util\Translation\Translation

Esta es la clase principal para gestionar las traducciones de una entidad. Ofrece varios métodos para crear o persistir un TranslatableContent:

Otras clases que se pueden usar y que están dentro de Optime\Util\Translation\Translation son:

• Optime\Util\Translation\TranslatableContentFactory
  • newInstance(array $contents = []): TranslatableContent
  • fromString(string $content): TranslatableContent
  • load(TranslationsAwareInterface $entity, string $property): TranslatableContent
• Optime\Util\Translation\Persister\TranslatableContentPersister
  • prepare(TranslationsAwareInterface $targetEntity): PreparedPersister
• Optime\Util\Translation\Persister\PreparedPersister
  • persist(string $property, TranslatableContent $translations): void

Las clases y métodos anteriores se pueden usar directamente desde el servicio Optime\Util\Translation\Translation.

Uso en formularios:

Para poder implementar formularios con campos de traducción tenemos dos opciones.

Optime\Util\Form\Type\TranslatableContentType

Este tipo de formulario trabaja en conjunto con la clase TranslatableContent y lo que permite es renderizar tantos campos como locales tenga configurada la plataforma.

Se usa para cuando no estamos trabajando directamente con una entidad de doctrine.

Ejemplo de uso:

Optime\Util\Form\Type\AutoTransFieldType

Este tipo de formulario se usa para trabajar directamente con entidades de doctrine, internamente se encarga de cargar las traducciones del campo traducible y cuando se envia el form. es posible persistir dichas traducciones del campo.

Se usa para cuando estamos trabajando con una entidad de doctrine.

Ejemplo de uso:

Consideraciones importantes al usar traducciones

Cuando estamos cargando o persistiendo traducciones es importante que las entidades estén cargadas en el locale por defecto de la plataforma y no en el locale de la url. Ya que de lo contrario se van a guardar los valores traducidos en locales diferentes a los esperados.

Por lo que para poder cargar o persistir las traducciones se debe haber cargado la entidad en el locale por defecto o usar el siguiente código para que la entidad se refresque en el locale por defecto:

Si se intentar cargar o persistir traducciones y la entidad no está en el locale por defecto, la app lanzará una excepción indicando el error.

Atributos para controladores

Optime\Util\Http\Controller\HandleAjaxForm

Clase de tipo atributo que permite cambiar el status de la respuesta de un formulario invalido a 400 (Bad Request) cuando la petición es ajax. Esto es útil para cuando se está tratando un formulario por medio de un ajax y se quiere saber por javascript si hubo errores de validación y así mostrar dichos errores en el cliente sin recargar la página.

Por otro lado, esta clase permite detener las redirecciones cuando son peticiones ajax, por ejemplo cuando se guarda un form y se hace un redirect, podemos detener el redirect y convertir la respuesta a un status 200 para cuando sea por ajax el envío del form.

Ejemplos:

Esta clase recibe varios argumentos en el constructor:

• type null por defecto, se puede indicar un tipo de form para que solo se active el handler cuando el form coincida con el tipo. Esto es últil solo si la acción está manejando multiples formularios.
• invalidStatus Status http a retornar cuando el form sea invalido. por defecto retorna el 400.
• preventRedirect Indica si se debe evitar cualquier redirect al enviar y procesar el formulario de form exitosa.
• replaceRedirectContent Indica si se debe reemplazar el contenido de la respuesta cuando es un redirect o no. Si está true, el contenido de la respuesta será un "Ok".

Optime\Util\Http\Controller\PartialAjaxView

Clase de tipo atributo que permite retornar de una respuesta html con twig solo una parte o varias partes de dicho html y no todo su contenido.

Esto es últil para cuando se tiene una página que puede cargar tanto de forma directa con la url en un navegador, como por medio de un ajax con javascript y que solo necesitemos una parte de dicha página html.

Ejemplos:

Esta clase recibe varios argumentos en el constructor:

• name 'default' por defecto, sirve para indicar la o las secciones que vamos a extraer del twig, contenidas en los tag "ajax_view".
• method permite indicar un método http (get, post, etc) para que el atributo solo se active si la petición es del tipo indicado.
• ignoreOnEmpty Si es true, significa que si no se encontró la etiqueta ajax_view en el twig o su contenido está vacio, se debe retornar la pagina completa. Si es false, retornaría un string vacio.

Otros ejemplos de uso:

Para los siguentes ejemplos vamos a partir del siguiente twig:

Este twig tiene tres etiquetas ajax_view, dos con nombre (header y table) y una sin nombre, que toma por defecto el nombre "default" al no indicarle nada.

Ejemplo de especificar la sección a retornar:

En este casi, si la petición es ajax, solo se retornará la parte envuelta en el tag {% ajax_view table %} aunque hayan varias etiquetas. en dicho twig.

Retornar una sección dependiendo del tipo de petición:

Para el método index, si la petición es ajax y de tipo "post", se va a retornar la sección "table", de resto se va a retornar la sección "header".

Para el método other, si la petición es ajax y de tipo "post", se va a retornar la sección "table", de resto se va a retornar la sección "default".

Retornar varias secciones:

Este es una caso particular, y si se desean retornar varias secciones, se deben pasar como un arreglo al atributo, esto va hacer que cuando la petición sea ajax, el resultado va a ser una respuesta de tipo json con las secciones como indices de un objeto json y los valores van a ser los contenidos html de dichas secciones.

Esto es útil si por ejemplo tenemos una página con un filtro por ajax, y necesitamos que al filtrar, se actualize un listado y un contador que está alejadod e dicho listado, entonces podemos tener dos secciones a retornar, una con el listado y otra con el contador:

Optime\Util\Http\Request\ArgumentValue\LoadFromRequestContent

Clase de tipo atributo que permite indicar que queremos cargar los datos que vienen de una petición application/json en un objeto o un array, usando el serializador de Symfony.

Ejemplos: