Writing a Package FAQ for Versioning and Compatibility
Package users need to know whether a release fits their project, what an update changes, and what they must do to upgrade.…
When a Laravel endpoint creates a database record, it often needs every field required for a valid record. When it updates a record, it may accept either a complete replacement or only the fields the client wants to change. Set validation rules to match that difference. Laravel does not automatically require fields on create or make them optional on update.
A Form Request is a custom Laravel request class that holds validation rules and checks whether a user may make an incoming request. Use separate Form Requests when create and update have different requirements. Reuse one when both operations follow the same contract and the shared rules are clear.
Decide whether an update replaces the whole record or changes only the fields the client sends. A full replacement can require every field needed to define the record. A partial update should allow omitted fields while checking any fields the client does send. Laravel provides rules for both approaches; choose the ones that match the endpoint’s requirements.
For example, a create request might require a name and email address. A full update might require both fields again. A partial update might let the client omit either field, but reject an empty value when the client includes it.
sometimes makes Laravel apply a field’s rules only when the request includes that field. Combine sometimes with required to let a partial update omit the field while requiring a nonempty value when it is included. The nullable rule allows an included field to have a null value. Laravel’s default middleware converts empty strings to null, so use nullable when the request allows that value. The Laravel validation documentation also explains these rules and conditional requirements such as required_if.
For example, a partial update can use:
'name' => ['sometimes', 'required', 'string'],
If the endpoint accepts null for a field, add nullable and check that the other rules allow it. Use required_if or Rule::requiredIf when one input makes another field necessary. Use exclude_if to skip a field and remove it from the validated data when a specified condition is met.
A create request checks whether another record already uses the submitted value. An update request must exclude the record being changed, so its existing value remains valid when unchanged. Laravel supports this with Rule::unique(...)->ignore(...).
use Illuminate\Validation\Rule;
// Create
'email' => ['required', 'email', Rule::unique('users', 'email')],
// Update: $user is the model being updated
'email' => [
'sometimes',
'required',
'email',
Rule::unique('users', 'email')->ignore($user),
],
Laravel applies the update rule only when the request includes email. It allows the current user’s existing email and rejects an email assigned to another user. Laravel’s unique validation rule accepts a model or a key generated by the system to exclude that record. Do not pass a value from the user’s request to ignore; use the trusted model resolved for the update route.
To make a value unique only within an account or another group of records, add that condition to the rule. Laravel includes records marked as deleted but still stored in the database in unique checks by default. Use withoutTrashed() when the application’s policy allows a deleted record’s value to be reused.
Laravel can return a validation error to the client before writing the value. A database unique index protects the stored data. Keep the index even when the request checks uniqueness, because two requests can pass that check before either one writes its value.
Laravel Form Requests handle two decisions: rules() checks the submitted data, and authorize() checks whether the user has permission to perform the action. Valid data does not give the user permission to update a record. For an update, authorization should check the record identified by the route.
Use separate classes, such as StoreUserRequest and UpdateUserRequest, when the operations have different required fields, uniqueness rules, permissions, or error messages. Each class then states its requirements directly, without many conditions that branch between create and update.
Reuse one Form Request when both operations have the same validation and authorization requirements. If they share some rules but differ in important ways, keep each operation’s distinct behavior clear and extract only the shared rules. Laravel supports Form Requests but does not require you to use either a shared or separate class.
Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.
Take a look at vroni.com