Laravel Action Otp Laravel Package

Getting Started

• Install the package, publish its config and migrations, then run php artisan migrate. Start with config/otp.php, the package routes, ActionOtp, ValidOtpCode, and ConfirmSession.
• First use case: add OTP verification to a login or sensitive action. Resolve the identifier server-side, send a code, validate it with ValidOtpCode, and let the package controllers confirm the session.
• In v2.1.0, look first at ActionOtp::identifyUsing(). It controls which identifier the verify and resend routes use, so it is the main integration point for multi-tenant, authenticated-user, or route-model-based flows.

Implementation Patterns

• Register a server-side identifier resolver once, usually in a service provider:

  ActionOtp::identifyUsing(function ($request) {
      return $request->user()?->phone
          ?? $request->route('user')?->phone;
  });
  

  The verify and resend routes will use this value and ignore the identifier field in the request body.

• Use identifyUsing() for flows where the identifier must not be client-controlled: authenticated user profile changes, admin-triggered verification, tenant-scoped phone/email verification, or signed route parameters.

• Return null deliberately when the identifier cannot be resolved. The package answers with an empty response and does not count an attempt. This is useful for avoiding user enumeration, but make sure your frontend treats an empty response as a neutral outcome rather than a validation failure.

• Pass a non-blank purpose to ValidOtpCode. A blank purpose now fails validation instead of throwing, so it will surface as a normal validation error. Keep purposes consistent between code generation and validation.

• Let the package controllers handle ConfirmSession for code, magic-link, and verify routes. If you verify a ConfirmSession manually outside those routes, set ConfirmSession::SESSION_KEY yourself in the session before relying on it.

• In tests, use ActionOtpFake without constructor arguments. Prefer resolving it from the container or the package's fake helper instead of instantiating it directly.

• Wrap verify and resend behind authentication and rate limiting where appropriate. The identifier resolver decides the target, but throttling still belongs at the route/middleware layer.

Gotchas and Tips

• identifyUsing() is global for the verify and resend routes. Make the resolver deterministic per request and avoid side effects; it may be called on both routes.
• Request identifier fields are ignored on verify and resend once a resolver is set. Update API docs and frontend clients so they do not assume the submitted phone/email is authoritative.
• A resolver returning null does not increment the attempt counter. Do not use the empty response as proof that an OTP was checked; log or monitor it separately if you need visibility.
• Blank purposes are now validation failures. If you previously relied on an exception for missing purpose configuration, update error handling and tests.
• Manually verifying ConfirmSession is a breaking change in v2.1.0. Code outside the package controllers must set ConfirmSession::SESSION_KEY in the session; otherwise the confirmation will not be recognized.
• ActionOtpFake no longer accepts a Recorder. Remove the argument from manual instantiations in tests; the constructor change is small but will fail immediately if missed.
• When debugging failed verification, check the resolver output first, then the purpose, then the session key. These are the three most likely integration points affected by this release.
• Extension points worth knowing: the identifier resolver, package translations (pl, de were reworded), the ValidOtpCode rule, and the fake used in tests.