Rewrite docs

[tijsverkoyen]

Summary by Sourcery

Rewrite and reorganize documentation for the FrameworkCoreBundle, consolidating developer and frontend docs into a clearer top-level docs structure without changing runtime code.

Documentation:

• Document audit trail configuration and usage, including attribute options, log format, performance notes, and troubleshooting.
• Expand breadcrumb, title, Stimulus, AJAX client, mails, dark mode, no-results, button placement, and asset mapper docs with clearer prerequisites, options tables, examples, and troubleshooting guidance.
• Introduce new documentation pages for forms, pagination, file and image uploads, encrypted fields, menus, language switcher, date pickers, and the overall bundle index.
• Update frontend development guidance (Sass, JavaScript, AssetMapper, dark mode, separate frontend layout) to be more structured and task-oriented.
• Improve the README to better describe the bundle’s purpose, requirements, and entry point into the documentation.
• Add a CLAUDE.md file to describe the bundle’s architecture and development conventions for AI-assisted tooling.

[sourcery-ai]

Reviewer's Guide

Rewrite and reorganize documentation for multiple bundle subsystems (audit trail, breadcrumbs, titles, forms, uploads, pagination, menus, frontend, etc.), moving docs out of docs/development/docs/frontend into top-level docs/, enriching each with prerequisites, options tables, examples, troubleshooting, and adding new overview and contributor docs (docs/index.md, CLAUDE.md).

File-Level Changes

Change	Details	Files
Restructure and expand audit trail documentation with configuration, attribute options, log format, manual logging, performance notes, and troubleshooting.	Move audit trail doc from docs/development to docs/audit-trail.md and tighten introduction/prerequisites. Clarify that DoctrineAuditListener is auto-registered and explain Monolog channel setup. Document #[AuditTrail] options (fields, withData) and action codes table. Add guidance on manual logging via AuditLogger, including a realistic controller example. Add performance and troubleshooting sections (listener behaviour, field filtering, masking sensitive data).	docs/development/audit-trail.md docs/audit-trail.md
Rewrite breadcrumb documentation to describe attribute options, rendering, and troubleshooting, and move it to the new docs location.	Retitle and reorient doc as Breadcrumbs, adding a high-level feature description and prerequisites. Document full #[Breadcrumb] parameter set (title, route, parent, parameters) including interpolation rules and repeatability. Provide a canonical Twig rendering example for breadcrumbTrail. Add troubleshooting section covering common misconfigurations (missing method attribute, interpolation issues, parent chain, translations).	docs/development/breadcrumb.md docs/breadcrumb.md
Modernize frontend development docs (AssetMapper, Sass, JS structure, dark mode, separate frontend layout) and move them to top-level docs/.	Clarify AssetMapper usage, install/compile commands, and where main CSS lives. Improve Sass guidance, including variable overrides, dark mode usage, component organization, and folder layout. Document JS organization (Stimulus controllers, app entry, component overrides). Explain setup for a separate public/frontend layout for CSS and JS, including extra Sass entry and config hooks. Remove obsolete reference to components.html and delete that file.	docs/frontend/frontend-development.md docs/frontend/asset-mapper.md docs/frontend/components.html docs/frontend/dark-mode.md docs/frontend/installation.md docs/frontend/no-results.md docs/frontend/mails.md docs/frontend/stimulus.md docs/frontend/ajax-client.md docs/frontend/asset-mapper.md docs/frontend/frontend-development.md docs/asset-mapper.md docs/frontend-development.md docs/ajax-client.md docs/stimulus.md
Expand AJAX client documentation with prerequisites, import instructions, file upload example, and troubleshooting.	Describe the client as a pre-configured Axios wrapper with CSRF, toasts and busy buttons. Add import example for Stimulus controllers and reference to installation docs. Include multipart file upload example using FormData and custom headers. Add troubleshooting for CSRF issues, missing toasts, and timeout overrides.	docs/frontend/ajax-client.md docs/ajax-client.md
Enhance page title system documentation and move it to top-level docs/title.md.	Add high-level description of how #[Title] and breadcrumbs determine <title>/<h1> and expose pageTitle in Twig. Document #[Title] options (title, parent, extend) and attribute constraints (method-only, non-repeatable). Clarify resolution order, parameter interpolation, and parent chain recursion. Add troubleshooting notes (placeholder resolution, missing site name, parent chain issues, extend: false usage).	docs/development/title.md docs/title.md
Rewrite Stimulus controller documentation to describe bundle-provided controllers, lifecycle hooks, and prerequisites.	Retitle to focus on Stimulus controllers provided by the bundle rather than generic UX info. Add prerequisites for asset installation and controller import wiring. Document common lifecycle hooks (connect, disconnect) and guidance for extending bundle controllers. Clean up minor formatting around existing controller docs (e.g. confirm modal section).	docs/frontend/stimulus.md docs/stimulus.md
Clarify button placement conventions and accessibility in shared layout documentation.	Add explanation of the two toolbar regions and their intended use for primary vs secondary actions. Slightly expand fixed bottom toolbar section and positions (left/center/right) with typical usage. Clarify cross-form submit behaviour using form="{{ form.vars.id }}". Add accessibility guidelines (button type, destructive action placement, aria-labels for icon-only buttons).	docs/development/button-locations.md docs/button-locations.md
Extend mail template documentation with styling guidance using Foundation for Emails and logo constraints.	Add a section on template styling with Foundation for Emails and link to their docs. Document logo recommendations (fixed width, GIF for compatibility, and width attribute alignment). Retain existing async mail sending guidance and templates snippet.	docs/development/mails.md docs/mails.md
Introduce comprehensive docs for forms, including custom form types and automatic type extensions.	Create new docs/forms.md describing ImageType, FileType, BelgiumPostCodeType usage with examples. Document full options tables for image/file form types including preview/remove flags and validation messages. Describe form type extensions for date/time (Flatpickr), collection drag-and-drop and min/max, and password toggles. Explain translation behaviour for form labels and how to override label text via translations.	docs/forms.md
Add detailed pagination documentation covering repository/controller usage, Twig helper, API, sorting, filter persistence, and troubleshooting.	Create docs/pagination.md with canonical repository and controller examples using Paginator and paginate(). Document Twig integration via pagination() function and hasToPaginate checks. Provide full Paginator API reference including page window helpers and page size override. Show patterns for sortable lists and session-persisted filters, plus troubleshooting tips.	docs/pagination.md
Add dedicated guides for uploading images and files via AbstractImage/AbstractFile, custom DBAL types, lifecycle hooks, and forms.	Create docs/uploading-images.md documenting AbstractImage, fallback images, DBAL type, entity callbacks, and ImageType usage. Create docs/uploading-files.md documenting AbstractFile, DBAL type, entity callbacks, and FileType usage. Include template examples and API notes (web paths, deletion, file replacement behaviour). Add troubleshooting notes for missing uploads, fallback behaviour, directory issues, and preview problems.	docs/uploading-images.md docs/uploading-files.md
Document menu system based on KnpMenu and ConfigureMenuEvent, including listener patterns, helpers, icons, and nested menus.	Create docs/menu.md explaining ConfigureMenuEvent, MenuBuilder, and how consuming apps register listeners. Provide example MenuListener extending DefaultMenuListener with role checks and route matching extras. Document helper methods, child route activation, icon conventions, and nested dropdown construction. Add troubleshooting for active state, role visibility, and listener registration issues.	docs/menu.md
Add encrypted field documentation explaining EncryptedDBALType, key management, behaviour, limitations, and migration guidance.	Create docs/encrypted.md describing sodium-based field-level encryption via custom DBAL type. Document ENCRYPTION_KEY generation, configuration, and type registration in Doctrine. Explain how read/write conversion works and the resulting DB format, plus non-searchable limitation. Provide migration strategy and troubleshooting for key/format mismatches and conversion errors.	docs/encrypted.md
Introduce a central documentation index and contributor guide for using the bundle and its docs.	Add docs/index.md as an entry point summarizing subsystems, attributes, services, and external packages. Describe request lifecycle, key injectable services, attribute-based configuration, and architecture overview. Add CLAUDE.md to describe bundle purpose, requirements, commands, architecture, and where to update docs.	docs/index.md CLAUDE.md
Document usage of date/time pickers powered by Flatpickr and how to configure constraints and custom options.	Create docs/using-date-pickers.md explaining default Flatpickr activation on core date/time form types. Describe additional form options (minimum_date, maximum_date, format) and their expected formats. Show how to pass native Flatpickr options via data-date-* attributes. Add troubleshooting around widget/html5 configuration and format mismatches.	docs/using-date-pickers.md
Document language switch mechanism, configuration of locales, and Twig snippet for the switcher.	Create docs/language-switch.md describing locale routing requirements and use of _locale parameter. Show how to configure supported locales via parameters.locales in services.yaml. Provide complete Twig snippet for the dropdown-based language switcher, including route/param merge. Add troubleshooting for locale change issues and missing locales parameter.	docs/language-switch.md
Document dark mode theming hooks, variable overrides, disabling procedure, and troubleshooting.	Create docs/dark-mode.md explaining the theme cookie, data-bs-theme, and theme() Twig helper. Show how to override dark mode SCSS variables and link to Bootstrap 5.3 color modes docs. Describe how to completely disable dark mode (SCSS flag, logo, toggler partial). Add troubleshooting for toggle visibility, cookie persistence, and variable application.	docs/dark-mode.md
Document standardized no-results UI component usage, including filter-aware variants and accessibility guidance.	Create docs/no-results.md demonstrating base data-no-results markup with image and translatable text. Provide variant that includes a reset-filters link when empty state is filter-driven. Explain accessibility rationale (decorative image alt and meaningful text).	docs/no-results.md
Clean up obsolete development/deployment docs that have been replaced by new top-level documentation.	Remove older docs under docs/development/ that now have equivalents in docs/ (forms, menu, pagination, uploads, encrypted, etc.). Remove deployment and pdf/autocomplete/migrations fixtures docs that are out of scope for this bundle-level docs rewrite.	docs/deployment/deployment.md docs/development/autocomplete.md docs/development/encrypted.md docs/development/fixtures.md docs/development/forms.md docs/development/language-switch.md docs/development/menu.md docs/development/migrations.md docs/development/pagination.md docs/development/pdf.md docs/development/uploading-files.md docs/development/uploading-images.md docs/development/using-date-pickers.md docs/frontend/components.html docs/frontend/dark-mode.md docs/frontend/installation.md docs/frontend/mails.md docs/frontend/no-results.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[jonasdekeukelaere]

Hmm ik smijt dat eigenlijk zo goed als altijd in de UpdateController (en dan via modal in template)

[tijsverkoyen]

Mja, moeten we eens over hebben.
Ik vind dat op zich wel handig om aparte Delete Controller te hebben. Voordelen die ik zie:

• Heel expliciet
• Single responsibility
• Je kan met form werken

[jonasdekeukelaere]

Maybe ja

[jonasdekeukelaere]

Zou het "beter" zijn om de icu-versie te gebruiken? En mss ook direct NL? messages+intl-icu.nl.yaml

[tijsverkoyen]

Best keer bespreken, want mijne maat Claude zegt:

Het hangt af van wat je nodig hebt, maar voor nieuwe projecten is messages+intl-icu.nl.yaml meestal de betere keuze.

ICU (+intl-icu)

• Standaard ICU MessageFormat syntax, dus overdraagbaar naar andere tools en vertalers die ICU kennen (Crowdin, Lokalise, etc. ondersteunen dit native)
• Correcte pluralisatie en gender-regels per taal, niet Symfony's eigen ||-syntax
• Vereist de intl PHP-extensie (heb je vrijwel zeker al actief)
• Iets duurder in performance omdat het door de ICU-formatter gaat, maar in de praktijk negeerbaar

Plain (messages.nl.yaml)

• Simpeler, geen ICU-syntax nodig, direct leesbaar voor niet-technische mensen
• Eigen Symfony pluralisatie-syntax ({0} geen|{1} één|]1,Inf[ meerdere), minder standaard maar prima voor eenvoudige gevallen
• Geen externe dependency nodig

Voor projecten met vooral simpele labels en foutmeldingen zonder complexe pluralisatie of meertalige nuances: plain messages.nl.yaml is voldoende en simpeler, sluit ook aan bij je principe van simplicity first.

Zodra je content hebt met pluralisatie, datums, getallen of gender die door niet-developers vertaald wordt (bijvoorbeeld via een vertaalbureau of externe tool), is ICU de juiste keuze omdat het de standaard is en minder foutgevoelig bij vertaling.

Concreet voorbeeld, pluralisatie van "item":

Plain Symfony syntax (messages.nl.yaml):

cart.items: '{0} Geen items|{1} Één item|]1,Inf[ %count% items'

ICU syntax (messages+intl-icu.nl.yaml):

cart.items: '{count, plural, =0 {Geen items} =1 {Één item} other {{count} items}}'

Verschil zit vooral in de interval-syntax. Symfony's plain versie gebruikt wiskundige intervallen (]1,Inf[ betekent "van 1 tot oneindig, exclusief 1"), wat minder intuïtief is. ICU gebruikt expliciete plural-categorieën (zero, one, few, many, other) die per taal correct worden toegepast door de ICU-library zelf, dus voor talen met complexere pluralisatieregels dan Nederlands (zoals Pools of Arabisch) werkt dit correcter out of the box.

Tweede verschil, placeholders in ICU zijn niet-prefixed ({count} in plaats van %count%), en je kan er direct formatting aan toevoegen:

# ICU, met getalformattering
order.total: 'Totaal: {amount, number, currency}'

# Plain, moet je zelf formatteren in PHP/Twig
order.total: 'Totaal: %amount%'

[jonasdekeukelaere]

Hmm, hier doet ik in DTO eigenlijk nooit constructor en doe ik het pas in UpdateMessage (dan wel met entity in constructor)

[tijsverkoyen]

Heb je ergens een voorbeeld?

[jonasdekeukelaere]

DTO: https://git.sumocoders.be/dyzo/app-dyzo-be/-/blob/master/src/DataTransferObject/ExportCity/ExportCityDataTransferObject.php?ref_type=heads
Create: https://git.sumocoders.be/dyzo/app-dyzo-be/-/blob/master/src/Message/ExportCity/Create.php?ref_type=heads
Update: https://git.sumocoders.be/dyzo/app-dyzo-be/-/blob/master/src/Message/ExportCity/Update.php?ref_type=heads

[jonasdekeukelaere]

Hmm ik doe meestal een add method en een save method, want bij update is persist van entity niet nodig

[tijsverkoyen]

Mja, ik snap het.
Maar heb al paar keer gezien dat er dan in add een save werd gedaan, en dan is dat zo verwarrend.
Keer bespreken.

[jonasdekeukelaere]

https://git.sumocoders.be/dyzo/app-dyzo-be/-/blob/master/src/Repository/ExportCity/ExportCityRepository.php?ref_type=heads#L19