Download the PHP package tihloh/prefab-auth without Composer

Prefab Auth

Prefab Auth provides framework-independent authentication for PHP applications while allowing the host project to keep ownership of its users, database and application structure.

Use only password authentication if that is all you need. Add social authentication and other integrations when the application grows.

Auth does not own the project's user table. Any compatible user source can be connected through the Auth contracts, including Prefab Users or a project/framework adapter.

Requirements

• PHP 8.1 or newer
• Composer when installed as a package

Installation

Responsibilities

Prefab Auth handles authentication concerns such as:

• password login and logout;
• current authenticated user/session lookup;
• custom user-provider integration;
• automatic use of compatible Prefab Users and Prefab Logs capabilities when available;
• isolated native PHP sessions by default;
• social sign-in;
• social account linking and unlinking;
• OAuth state validation;
• password-reset/social-account storage support;
• structured authentication log payloads.

It deliberately does not require the application to replace its existing user model or database design.

1. Password authentication

If Prefab Users is already available, normal usage is intentionally small:

Auth resolves missing compatible resources on first use. You do not normally call internal Prefab configuration methods yourself.

For a completely standalone Auth installation, provide your own user provider explicitly:

A custom session implementation may also be supplied when needed.

2. Current authenticated user

Typical use:

3. Automatic session isolation

Prefab Auth separates its native PHP session from other applications by default.

For example:

No session configuration is required for this protection.

Prefab also namespaces its own session keys so that even when PHP was started before Auth, Prefab authentication values remain application-scoped.

The default resolution is:

An explicit shared namespace may be configured through the global Prefab configuration:

Using the same explicit namespace gives applications the same Prefab session identity. By default an explicit namespace uses cookie path /; path and domain can be overridden for unusual deployments or cross-host sharing.

Optional shared session settings include:

Session isolation is the default. Sharing must be intentional through common configuration.

4. User-provider ownership

Prefab Auth authenticates users; it does not require its own users table.

A compatible user object implements AuthenticatableUserInterface. Existing project models, Prefab Users, Laravel model adapters or another implementation can participate without making Auth dependent on one storage design.

5. Cooperation with Prefab Users

Prefab Auth accepts any identifier string. When Prefab Users is connected, Auth delegates identifier resolution to Users.

By default, Users resolves login identifiers by email only. Projects may configure one or more mapped login fields:

With a mapping such as:

the normal Auth API accepts either username or email:

Auth itself remains identifier-agnostic. Prefab Users owns the configured lookup fields. Older Users integrations that do not expose findByIdentifier() continue to fall back to email lookup.

Prefab Users publishes a compatible user-provider capability. Auth can discover it automatically:

Normal application code remains:

Explicit configuration always remains available and wins over automatic discovery.

6. Cooperation with Prefab Logs

When Prefab Logs is available, Auth can discover its logger capability and record infrastructure authentication events such as login, failed login and logout.

The application does not need to insert audit rows around every authentication call.

7. Authentication result

Authentication returns a result instead of forcing HTML, JSON, redirects or exceptions for normal credential failure:

Useful request context can be supplied:

8. Social authentication

Social authentication is optional. Providers are registered through SocialProviderRegistry and may implement Prefab's provider contract directly or use a callback adapter.

Native OAuth state storage uses the same isolated Prefab session scope as password authentication.

9. Starting social sign-in

10. Handling the social callback

OAuth state is validated as part of the flow.

11. Permissions and Routes

Auth answers who the current user is. Permissions answers what that user may do. Routes may consume authentication/authorization capabilities through compatible integration.

The modules remain independently installable.

12. Error handling

Prefab Auth should fail as a library, not take over the host application. Missing required providers/resources produce clear, catchable exceptions. Invalid credentials return a normal authentication result.

13. Diagnostics

Automatic integration can be inspected when troubleshooting:

Normal application code does not need this.

14. API quick reference

15. Design philosophy

The simple authentication API remains the same as the application grows.

That is the goal of Prefab Auth: authentication that can stand alone, cooperate automatically when useful, isolate itself safely by default, and never require the application to become a specific framework.