Rule Builder Laravel Package

Getting Started

• Confirm the package’s PHP/Laravel constraints in composer.json before upgrading. v4.0.0 is a major release, so treat it as a breaking change even though the release note is short.
• Install/upgrade with composer require <vendor>/<package>:^4.0. If the package ships a service provider or config file, publish it as documented and clear caches (php artisan config:clear, composer dump-autoload).
• Look first at the package README, CHANGELOG.md, and the src/Rules directory. The rules are usually small classes implementing Laravel’s ValidationRule contract; reading one or two gives you the intended usage pattern immediately.
• First use case: drop a package rule into a FormRequest alongside Laravel’s built-in rules:

use Vendor\Package\Rules\SomeRule;

public function rules(): array
{
    return [
        'email' => ['required', 'email', new SomeRule()],
        'nickname' => ['sometimes', 'string', 'max:255'], // formerly: ['optional', ...]
    ];
}

• If you are migrating from v3, start by searching the codebase for existing uses of the removed optional rule before writing any new rules.

Implementation Patterns

• FormRequest-first usage. Instantiate rule objects in rules() rather than relying on string rule names. This keeps IDE support, constructor arguments, and custom messages explicit.
• Compose with Laravel built-ins. Package rules work best as part of a rule array: ['required', 'string', new SomeRule(), 'max:255']. Use bail when later rules are expensive and should not run after a failure.
• Replace optional deliberately. The removed rule most likely expressed “validate this field only when it is present.” In v4, map that intent to Laravel’s native rules:
  • sometimes — run the remaining rules only if the field is present.
  • nullable — allow null while still validating non-null values.
  • exclude — remove the field from validated data entirely.
  • present — require the key to exist, even if its value is empty.
• Upgrade workflow. Create a branch, bump the constraint, run the full test suite, then grep for optional in rule arrays, new Optional, and Optional::class. Add regression tests around any field that previously used the removed rule.
• Testing pattern. Validate rules directly with Validator::make() in feature/unit tests. Cover the “field missing,” “field null,” and “field present with invalid value” cases — those are exactly the cases where the removed optional rule mattered.
• Inline validation. The same rule objects work outside FormRequests:

$validator = Validator::make($request->all(), [
    'phone' => ['nullable', new PhoneRule()],
]);

• Custom messages. If the package rules implement message() or expose translation keys, keep overrides in lang/ or pass a third argument to Validator::make() rather than editing vendor files.

Gotchas and Tips

• The optional rule is removed in v4.0.0. This is the primary breaking change. Any validation array containing 'optional', new Optional, or Optional::class will fail or behave differently after upgrading. Audit before deploying.
• Do not blindly replace optional with nullable. They are not equivalent. If the old rule skipped validation when the key was absent, sometimes is usually the correct replacement. If it allowed explicit null values, use nullable. If it stripped the field from validated output, use exclude.
• Search thoroughly. optional can appear as a string rule, a class import, a constructor call, a config array, or a test fixture. Search for optional, Optional, and optional with case-insensitive grep.
• Check package version constraints. A major version may also raise the minimum PHP or Laravel version. Run composer why-not <vendor>/<package> 4.0 if the upgrade will not resolve.
• Debugging rule failures. If a package rule fails unexpectedly, inspect its passes() method and confirm whether it receives the raw value, the full data array, or the validator instance. Rules implementing DataAwareRule or ValidatorAwareRule behave differently from simple ValidationRule implementations.
• Config and caching quirks. If the package publishes config, remember that config:cache can mask changes. Clear config and opcode caches after upgrading.
• Extension points. Prefer implementing Laravel’s ValidationRule contract or extending the package’s base rule class over modifying vendor code. If the package exposes macros or custom rule registries, use those to keep upgrades painless.
• Keep a migration note in your project. Record that v4 removed optional and which native rule replaced it in each context. Future contributors will otherwise reintroduce the removed rule from old examples or tutorials.