- How do I add custom fields to Sulu categories without modifying the domain model?
- Use the **Additional Data** tab provided by this bundle. Define your fields in a standard Sulu form XML file (e.g., `category_additional_data.xml`) and store them as a JSON column on the existing `ca_categories` table. No schema changes or migrations are required beyond adding the `additionalData` column.
- What Laravel/Sulu versions does this bundle support?
- This bundle is built for **Sulu CMS ~3.0** and requires **PHP 8.2+**. It follows Laravel’s Composer integration patterns but is primarily designed for Sulu-based projects. Ensure your Sulu installation meets these requirements before installing.
- Can I use this bundle in a Laravel/Lumen project without Sulu?
- No, this bundle is **Sulu-specific** and relies on Sulu’s CategoryBundle, AdminBundle, and form XML system. It won’t work in standalone Laravel/Lumen projects without Sulu CMS installed. For Laravel-only solutions, consider alternatives like Spatie’s Laravel Media Library or custom Eloquent traits.
- How do I configure the tab title and form key for the Additional Data section?
- Override the default tab title and form key in your project’s configuration (`config/packages/alengo_sulu_category_extra.yaml`). Use the `tab_title` and `form_key` parameters to match your admin setup. The bundle also requires a `resource_key` to link to your form XML file (e.g., `category_additional_data`).
- What field types are supported in the Additional Data form?
- The bundle supports all standard Sulu field types, including `text_line`, `single_select`, `multi_select`, `text_editor`, `media_selection`, and more. Define these in your form XML file (e.g., `config/forms/category_additional_data.xml`). Complex nested structures (like arrays of media) are supported but may require testing for JSON serialization limits.
- Will adding a JSON column impact performance for large category datasets?
- The JSON column adds minimal overhead for small to medium datasets (under 10K categories). For larger datasets (>50K categories), benchmark queries and consider partial indexing or materialized views. The bundle avoids joins by storing data directly on the `ca_categories` table, which is efficient for read-heavy workloads.
- How do I migrate existing category metadata from a custom table to this JSON column?
- Create a custom migration script to extract data from your existing table and transform it into JSON format. Use Doctrine’s `update` queries or a data mapper to populate the `additionalData` column. Test the script in a staging environment first to ensure data integrity.
- Are there security risks with storing arbitrary JSON in the database?
- The bundle follows Sulu’s security model, including role-based access control for the admin API endpoints (`/admin/api/category-additional-data/{id}`). However, validate JSON structure in your form XML (e.g., required fields, enum constraints) and use Doctrine lifecycle callbacks for runtime checks to prevent malformed data.
- Can I access the Additional Data fields in Twig templates?
- Yes, the JSON data is available on the `Category` entity as `additionalData`. Access it directly in Twig (e.g., `{{ category.additionalData.theme }}`) or use a custom Twig extension for convenience. For complex nested data, consider creating a DTO or repository method to simplify access.
- What alternatives exist if I need relational data instead of JSON?
- For relational data, consider Sulu’s built-in **Category Properties** or **Category Relations** features, or extend the `ca_categories` table with additional columns via migrations. If you need a more flexible EAV-like system, evaluate Sulu’s **PropertyBundle** or third-party bundles like `SuluPropertyBundle` for structured metadata.