README.md

Documentation — AppoloDev\SFToolboxBundle

Documentation exhaustive du bundle appolodev/sf-toolbox, classe par classe, avec description de chaque méthode et exemples d'usage. Organisée en miroir de l'arborescence src/ (un dossier par namespace, un fichier par classe — les couples trait+interface ou classe+classe compagnon étroitement liés, comme un Constraint/ConstraintValidator, sont regroupés dans un seul fichier).

Pour un agent Claude Code travaillant dans un projet qui dépend de ce bundle, préférez le Skill Claude Code — plus concis, pensé pour être chargé rapidement en contexte. Cette documentation docs/ est la référence exhaustive, pensée pour un lecteur humain (ou une lecture approfondie ponctuelle par un agent).

Domain

Entity/Concern — traits d'entité Doctrine

Classe	Description
Identifiable	Clé primaire UUID générée automatiquement.
Timestampable	Dates createdAt/updatedAt automatiques.
Sluggable	Slug généré à partir d'un champ title.
Publishable	Fenêtre de publication (dates de début/fin).
Activable	Flag enabled.
Archivable	Flag archived.
Blockable	Flag blocked.
Deletable	Flag deleted (suppression logique).
Authenticable	Champs et méthodes UserInterface (email, mot de passe, rôles, token de confirmation).
Geolocalizable	Champs d'adresse géolocalisée (adresse, ville, lat/lng).
FileUpload	Interface (sans trait) pour une entité porteuse d'un fichier.

Repository/Criteria — couche de requêtage fluide

Classe	Description
BuilderCriteria	Trait fondamental : initialisation du QueryBuilder et méthodes terminales (getResults, getSingleResult...). À lire en premier.
ComplexBuilder	Constructeur d'expressions bas niveau (andX/orX/eq/in...), utilisé dans complexQuery().
WhereCriteria	Filtres WHERE simples et chainables (eq, in, between...).
JoinCriteria	Jointures (with, join, leftJoin).
SelectCriteria	Projections et agrégations (select, countItem, max, sous-requêtes...).
GroupAndOrderCriteria	Tri, regroupement, indexation (order, groupBy, indexBy, random).
DateCriteria	Filtres de date pratiques (date, dateBetween, dateExpired...).
PublishableCriteria	Filtre "publié à la date courante" (published()), pour le concern Publishable.
GeolocalizableCriteria	Recherche géographique par rayon/bounding box (around, bounds).
DoctrineOperator	Enum des opérateurs de comparaison internes.
Expression/Expression	Contrat ExpressionInterface + implémentation StringExpr (fragment DQL brut).
Expression/Select	Expressions de projection PartialExpr/PartialDtoExpr.

Form

FormType

Classe	Description
TomSelectType	Champ texte enrichi par le widget JS Tom Select.
EntityTomSelectType	Équivalent basé sur des entités Doctrine.
CardRadioType	ChoiceType affiché en cartes sélectionnables.
GeolocalizableType	Champ caché recevant le JSON de géocomplétion.

DataTransformer

Classe	Description
StringToArrayTransformer	array ⇄ chaîne jointe par virgules.
ArrayToStringTransformer	array ⇄ chaîne, avec valeurs par défaut prioritaires.
UppercaseTransformer	Met en majuscules la saisie à la soumission.

Subscriber & Validator

Classe	Description
GeolocalizableSubscriber	Répercute automatiquement les données géocomplétées sur l'entité.
GeolocalizableConstraint	Valide que certains champs de l'adresse géocomplétée sont présents.

Maker

Command

Classe	Description
MakeDomainEntityCommand	make:domain:entity — scaffold entité + repository.
MakeScaffoldCommand	make:scaffold — scaffold CRUD complet (contrôleurs, formulaire, voter, templates).
InteractCommand	Trait utilitaire d'interaction console partagé par les deux commandes ci-dessus.

FileCreator

Classe	Description
AbstractFileCreator	Base commune des générateurs de fichiers (templates → fichiers réels).
EntityFileCreator	Génère entité + repository.
ScaffoldFileCreator	Génère le CRUD complet.

Security

Classe	Description
AbstractVoter	Base de Voter avec helpers canAllow()/canAllowAdmin().
IsNotGranted	Attribut (+ écouteur) inverse de #[IsGranted] natif.

Csv & Réponses HTTP

Classe	Description
CsvWriter	Génération de contenu CSV (délimiteur ;, BOM UTF-8).
CsvFileResponse	Réponse HTTP de téléchargement CSV.
ZipResponse	Réponse HTTP de téléchargement d'une archive zip générée à la volée.

Email, Twig, Utilitaires

Classe	Description
EmailMessage	Message + handler Messenger pour l'envoi d'emails templatés Twig.
IntlExtension	Filtre Twig localizedDate.
ArrayUtils	Recherche récursive de clé, aplatissement de tableau.
GeocompleteUtils	Parseur du JSON de géocomplétion.
UuidUtils	Détection de chaîne UUID valide.

Câblage du bundle

Classe	Description
SFToolboxBundle	Point d'entrée du bundle Symfony.
SFToolboxExtension	Extension de conteneur : chargement des services + configuration injectée dans le projet consommateur.
ScriptHandler	Script Composer qui lie le Skill Claude Code dans les projets consommateurs.

Parcours conseillés

• Créer une nouvelle entité de A à Z : MakeDomainEntityCommand → Identifiable/Timestampable → BuilderCriteria → MakeScaffoldCommand.
• Écrire une requête de repository : BuilderCriteria (point d'entrée) → WhereCriteria/ComplexBuilder selon la complexité des filtres.
• Ajouter une adresse géolocalisée à une entité : Geolocalizable (entité) → GeolocalizableType (formulaire) → GeolocalizableSubscriber (mapping auto) → GeolocalizableCriteria (recherche).