Nova Japanese Transformer Laravel Package

Getting Started

• Install the package with Composer and publish any config/views it ships with:

  composer require vendor/package
  php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"
  

• Start with the README section covering transformer fields and inspect the new Text and Textarea field classes. In a typical Laravel package layout these live under src/Fields/ or similar; confirm the exact namespace from the package docs.
• First use case: add a single-line Text field and a multi-line Textarea field to a form or resource definition so a model attribute can be edited and transformed consistently.

  use Vendor\Package\Fields\Text;
  use Vendor\Package\Fields\Textarea;
  
  // Example schema/field registration
  Text::make('title')
      ->rules(['required', 'string', 'max:255']);
  
  Textarea::make('description')
      ->rows(5)
      ->rules(['nullable', 'string']);
  

• If the package integrates with an admin/resource layer, register the fields where that layer expects field definitions. Verify whether fields are resolved automatically from the model or must be declared explicitly.

Implementation Patterns

• Basic field definition: use Text::make('attribute') for short values such as names, titles, slugs, and labels. Use Textarea::make('attribute') for descriptions, notes, bios, and other long-form plain text.
• Validation alongside fields: attach Laravel validation rules directly to the field definition where supported. Keep validation rules close to the field so form and API behaviour stay aligned.
• Defaults and placeholders: set default values for create forms and placeholders for guidance. For textareas, configure visible rows so long-form fields are usable without custom CSS.
• Model binding and transformation: bind fields to Eloquent attributes or accessors. If the package includes a transformer layer, use it to normalise input (trimming, null handling, line-ending normalisation) before persistence rather than scattering that logic in controllers.
• Reuse across resources: define common field sets in a trait, builder class, or shared schema method so Text and Textarea definitions are not duplicated across multiple forms/resources.
• Read/detail views: reuse the same field definitions for display where the package supports it. For textareas, preserve line breaks when rendering; for text fields, ensure output is escaped unless the package explicitly handles safe rendering.
• Integration with existing Laravel patterns: pair the fields with Form Requests or field-level rules, use Eloquent casts for structured data where relevant, and keep transformation logic in the field/transformer layer rather than in Blade templates.

Gotchas and Tips

• v1.0.0 is the first release: treat the public API as early. Pin the version in composer.json and review changelogs before upgrading, especially if you extend field classes or override views.
• Only text and textarea exist today: do not assume rich-text, markdown, or WYSIWYG behaviour. Textarea should be treated as plain multi-line text unless documented otherwise.
• Escaping and output safety: multi-line user input is a common XSS vector. Confirm that the package escapes output by default, and avoid {!! !!} when rendering textarea content unless you have explicitly sanitised it.
• Null and empty values: textarea inputs often submit empty strings. Decide whether the transformer should convert empty strings to null, and apply that consistently so validation and database constraints behave predictably.
• Line endings and whitespace: normalise \r\n to \n and trim surrounding whitespace if your application expects canonical text. Do this in the transformer or a dedicated mutator, not in multiple call sites.
• Config and view caching: after publishing config or overriding field views, run:

  php artisan config:clear
  php artisan view:clear
  

  Stale caches are a common reason field changes appear not to take effect.
• Field registration order: if fields are rendered in a schema, confirm whether order is determined by declaration order or an explicit sort/priority method. Missing fields are often a registration issue rather than a transformer bug.
• Extension points: check whether the package exposes custom field classes, macros, or view overrides. If you need behaviour beyond text/textarea, prefer extending the provided field classes over forking the package.
• Debugging: start by dumping the resolved field definition and the transformed value at the boundary between form input and model persistence. This quickly separates field configuration issues from transformer logic issues.