Frontend Laravel Package

Getting Started

1. Install the package with Composer and, if the service provider is not auto-discovered, register it in config/app.php.
2. Publish any package config and review the new README introduction block added in v1.0.2; it explains the validation model and where templates are expected to live.
3. Confirm the templates directory resolved by your application architecture. As of v1.0.2, template validation follows the architecture-defined templates directory rather than a package-local default.
4. Validate your first template:

use Vendor\Package\Facades\TemplateValidator;

$result = TemplateValidator::validate(resource_path('views/welcome.blade.php'));

if ($result->fails()) {
    // Inspect rule IDs and messages
    dump($result->errors());
}

Where to look first:

• The package config file for template path and validator registration.
• The README introduction block for the expected directory layout.
• The validator classes for the new stable rule IDs.
• Your application’s architecture/config layer that defines the templates directory.

First use case: guard template rendering or deployment by validating that a template exists inside the configured templates directory and passes the package’s rules. This is especially useful for user-supplied or generated templates that may point outside the expected directory.

Implementation Patterns

Use stable rule IDs in application code

v1.0.2 adds stable rule IDs to validators. Prefer asserting against IDs rather than human-readable messages so your tests and error handling survive wording changes.

$result = TemplateValidator::validate($path);

$this->assertTrue($result->fails());
$this->assertContains('template.location', $result->ruleIds());

Use the same IDs to map validation failures to API error codes, logs, or localized messages:

$messages = [
    'template.location' => 'The template must be inside the configured templates directory.',
    'template.syntax' => 'The template contains invalid syntax.',
];

Validate location before rendering

The new template location validation rejects files outside the templates directory. Use it as an explicit guard before compiling or rendering templates, particularly when the path comes from user input or a database record.

$validator = TemplateValidator::forPath($templatePath);

if ($validator->fails()) {
    abort(422, 'Invalid template location.');
}

return view($templatePath);

Follow the architecture-defined templates directory

Do not hardcode resource_path('views') or a package-specific path in your validation calls. Resolve the templates directory through the same architecture configuration the package now uses. This keeps CLI commands, queued jobs, and HTTP requests consistent.

$templatesPath = config('architecture.templates_path');

If your application supports multiple template roots, normalize and validate each root against the architecture configuration before passing paths to the validator.

Integrate into CI and deployment checks

Add a validation step to CI or a deployment script so templates outside the allowed directory fail fast:

// tests/Feature/TemplateValidationTest.php
public function test_all_application_templates_are_valid(): void
{
    $templates = File::allFiles(config('architecture.templates_path'));

    foreach ($templates as $template) {
        $result = TemplateValidator::validate($template->getPathname());

        $this->assertTrue(
            $result->passes(),
            "Template [{$template->getPathname()}] failed validation: " . $result->errors()->toJson()
        );
    }
}

Use in form requests and custom rules

Wrap the validator in a Laravel custom rule when validating uploaded or submitted template references:

class ValidTemplatePath implements ValidationRule
{
    public function validate(string $attribute, mixed $value, Closure $fail): void
    {
        $result = TemplateValidator::validate($value);

        if ($result->fails()) {
            $fail($result->firstError());
        }
    }
}

Register custom validators or override messages using the package’s extension points, and keep rule IDs stable in your own mappings.

Gotchas and Tips

• Changed path resolution may break existing setups. v1.0.2 changes template validation to follow the architecture-defined templates directory. If you previously relied on the package default or a hardcoded path, re-check your config and tests after upgrading.
• Expect new failures for files outside the templates directory. The added location validation will reject templates stored elsewhere, including partials, generated views, or package views outside the configured root. Audit those paths before deploying.
• Rule IDs are the stable contract, not messages. Use the new IDs for assertions and error mapping. Messages may be localized or changed without notice.
• Clear config caches when changing the templates directory. Laravel may serve stale configuration after deployment or config edits:

php artisan config:clear
php artisan config:cache

• Debug path resolution first. When a template unexpectedly fails location validation, log both the resolved templates directory and the normalized template path. Case sensitivity, symlinks, and relative paths are common causes of false failures.
• Symlinked template directories need care. If your templates directory is symlinked, ensure both the configured path and incoming paths are normalized consistently before validation.
• Do not bypass location validation for user-supplied paths. The new location check is the main protection against path traversal or accidental rendering of files outside the intended template root.
• Pin the version if you cannot migrate immediately. If your application depends on the previous template path behavior, constrain the package version until you have updated configuration and tests.
• Use extension points sparingly for location rules. Custom validators can add rules, but overriding the location rule itself may reintroduce the path-traversal risks this release addresses.
• Run the full template validation suite in CI. Because this release changes which directory is authoritative, a one-off local pass is not enough; validate all templates in the same environment configuration used in production.