Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 0 additions & 3 deletions .github/FUNDING.yml

This file was deleted.

9 changes: 5 additions & 4 deletions .github/workflows/phpunit.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,12 +18,13 @@ jobs:
strategy:
matrix:
php-version:
- "8.6"
- "8.5"
- "8.4"
- "8.3"

steps:
- uses: actions/checkout@v5
- uses: actions/checkout@v7
- run: composer install
- run: composer test

Expand All @@ -34,20 +35,20 @@ jobs:
# for github/codeql-action/upload-sarif to upload SARIF results
security-events: write
container:
image: byjg/php:8.4-cli
image: byjg/php:8.5-cli
options: --user root --privileged

steps:
- name: Git checkout
uses: actions/checkout@v4
uses: actions/checkout@v7

- name: Composer
run: composer install

- name: Psalm
# Note: Ignoring error code 2, which just signals that some
# flaws were found, not that Psalm itself failed to run.
run: ./vendor/bin/psalm
run: ./vendor/bin/psalm.phar
--show-info=true
--report=psalm-results.sarif || [ $? = 2 ]

Expand Down
142 changes: 142 additions & 0 deletions CHANGELOG-7.0.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
# Changelog - Version 7.0

> **Status: in development.** This document tracks changes landing on the `7.0` branch.
> Nothing here is released yet, and the contents may still change.

## Overview

Version 7.0 upgrades the underlying persistence stack to `byjg/micro-orm` 7.0 and
`byjg/anydataset-db` 7.0. `UsersService`, `UsersRepository`, `UserPropertiesRepository`, models
and mapper interfaces keep the same signatures as 6.x; the only API change is the renaming of the
`UserField` enum cases to PascalCase (see below).

Since 6.0 the library was already wired exclusively through `DatabaseExecutor` — the API that
became mandatory in anydataset-db 7.0 — so apart from that rename, the library code changed only
to fix the user id conversion in `UserPropertiesRepository` (see Bug Fixes).

## Breaking Changes

### Dependencies

| Package | 6.x | 7.0 |
|---|---|---|
| `byjg/micro-orm` | `^6.0` | `^7.0` |
| `byjg/anydataset-db` (transitive) | `^6.0` | `^7.0` |

### Removed driver query methods (via anydataset-db 7.0)

The query methods deprecated on the drivers since anydataset-db 6.0 no longer exist
(`$dbDriver->execute()`, `getIterator()`, `getScalar()`, `executeAndGetId()`, `getAllFields()`).
If your application still calls them on the driver instance it passes to AuthUser, migrate to:

```php
<?php
use ByJG\AnyDataset\Db\DatabaseExecutor;

$executor = DatabaseExecutor::using($dbDriver);
$executor->execute($sql, $params);
```

The recommended wiring is unchanged and keeps working as-is:

```php
<?php
$dbDriver = Factory::getDbInstance('mysql://user:pass@host/db');
$executor = DatabaseExecutor::using($dbDriver);

$usersRepository = new UsersRepository($executor, UserModel::class);
$propertiesRepository = new UserPropertiesRepository($executor, UserPropertiesModel::class);
$service = new UsersService($usersRepository, $propertiesRepository, LoginField::Username);
```

### Observer system (via micro-orm 7.0)

micro-orm 7.0 removed the global `ORMSubject` singleton and rewired observers on top of the
`DatabaseExecutor` observer mechanism. AuthUser does not use observers internally, but if your
application registered observers on the AuthUser repositories, review the
[micro-orm 7.0 changelog](https://github.com/byjg/micro-orm/blob/master/CHANGELOG-7.0.md):
observers are now scoped per executor instead of global.

### Development dependencies

- PHPUnit: `^10.5|^11.5` → `^12.5`
- Psalm: `vimeo/psalm ^5.9|^6.13` → `psalm/phar ^6.16`

### Enum cases renamed to PascalCase

Enum cases follow the ByJG standard and are written in PascalCase. The backed values did not
change, so `->value`, `from()`, `tryFrom()` and stored data are not affected; only code that
names a case (or reads `->name`) has to be updated.

| Enum | Before (6.x) | After (7.0) |
|---|---|---|
| `UserField` | `Created_at`, `uUpdated_at`, `Deleted_at` | `CreatedAt`, `UpdatedAt`, `DeletedAt` |

Not a plain change of casing: `UserField::uUpdated_at` is now `UserField::UpdatedAt`.

## Bug Fixes

- `UserPropertiesRepository` converted the user id for its queries without the database at
hand (`getUpdateFunctionValue($userid, null)`), so a UUID user id was always written as
`X'…'`. With byjg/micro-orm 7.0, which writes a UUID in the syntax of each database, the
repository now passes its executor, and the queries work on PostgreSQL (a native `uuid`)
and SQL Server too.
- `SessionContext::registerLogin($userId, $data)` lost `$data`: it stored the cache item in
place of the array, so `getSessionData()` never found the values passed at login.

## Migration from 6.x

1. Update the composer constraint:

```json
{
"require": {
"byjg/authuser": "^7.0"
}
}
```

2. If your application already wires AuthUser through `DatabaseExecutor::using()` (the documented
pattern since 6.0), no code changes are required.
3. If you still call the removed query methods directly on the `DbDriverInterface` instance,
migrate those calls to `DatabaseExecutor` (see table in the
[anydataset-db 7.0 changelog](https://github.com/byjg/anydataset-db/blob/master/CHANGELOG-7.0.md)).

## Requirements

- PHP 8.3, 8.4, 8.5 and 8.6 are now supported: `"php": ">=8.3 <8.7"`.
The previous `<8.6` upper bound excluded PHP 8.6, since `<8.6` is exclusive.

### ByJG dependencies

- `byjg/cache-engine` is now `^7.0`.
- `byjg/jwt-wrapper` is now `^7.0`.
- `byjg/micro-orm` is now `^7.0`.

While 7.0 is unreleased these resolve to `7.0.x-dev` from each component's
`7.0` branch, via `minimum-stability: dev` with `prefer-stable: true`.

## Toolchain

- PHPUnit updated to `^12.5`.
- Psalm is installed as `psalm/phar` instead of `vimeo/psalm`.

`vimeo/psalm` lists the PHP versions it supports and no published release includes
8.6, so as a dev dependency it made `composer install` fail on the 8.6 build job
before any test ran. `psalm/phar` requires only `php ^8.2` and bundles its own
dependencies, so it installs on every PHP version in the matrix and cannot conflict
with the project's. Psalm itself still refuses to *run* on 8.6, which is why the
Psalm job uses 8.5. `composer psalm` runs it.

- PHPUnit 13 is deliberately **not** used. It requires PHP `>=8.4.1`, breaking the
8.3 floor.

## Continuous Integration

- The build matrix now includes PHP 8.6.
- The Psalm job runs on PHP 8.5.

## Housekeeping

- `phpunit.xml.dist` renamed to `phpunit.xml`.
- The root `example.php` script was removed; see the [Examples](docs/examples.md) page.
28 changes: 9 additions & 19 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,8 @@ A simple and customizable library for user authentication in PHP applications us

[![Sponsor](https://img.shields.io/badge/Sponsor-%23ea4aaa?logo=githubsponsors&logoColor=white&labelColor=0d1117)](https://github.com/sponsors/byjg)
[![Build Status](https://github.com/byjg/php-authuser/actions/workflows/phpunit.yml/badge.svg?branch=master)](https://github.com/byjg/php-authuser/actions/workflows/phpunit.yml)
[![Opensource ByJG](https://img.shields.io/badge/opensource-byjg-success.svg)](http://opensource.byjg.com)
[![Opensource ByJG](https://img.shields.io/badge/opensource-byjg-success.svg)](https://opensource.byjg.com)
[![Install MCP Server](https://img.shields.io/badge/Install-MCP_Server-8A2BE2?logo=modelcontextprotocol&logoColor=white)](https://opensource.byjg.com/docs/ai/mcpserver-byjg-docs/)
[![GitHub source](https://img.shields.io/badge/Github-source-informational?logo=github)](https://github.com/byjg/php-authuser/)
[![GitHub license](https://img.shields.io/github/license/byjg/php-authuser.svg)](https://opensource.byjg.com/license)
[![GitHub release](https://img.shields.io/github/release/byjg/php-authuser.svg)](https://github.com/byjg/php-authuser/releases/)
Expand All @@ -32,9 +33,7 @@ This class can persist user data into session (or file, memcache, etc.) between
- [Mappers](docs/mappers.md)
- [Examples](docs/examples.md)

## Quick Start

### Installation
## Installation

```bash
composer require byjg/authuser
Expand Down Expand Up @@ -91,14 +90,6 @@ See [Getting Started](docs/getting-started.md) for a complete introduction and [
- **Field Mappers** - Transform data during read/write. See [Mappers](docs/mappers.md)
- **Extensible Model** - Add custom fields easily. See [Custom Fields](docs/custom-fields.md)

## Running Tests

Because this project uses PHP Session you need to run the unit test the following manner:

```bash
./vendor/bin/phpunit --stderr
```

## Architecture

```text
Expand Down Expand Up @@ -128,14 +119,13 @@ Because this project uses PHP Session you need to run the unit test the followin

This project is licensed under the MIT License - see the [LICENSE](https://github.com/byjg/php-authuser/blob/master/LICENSE) file for details.

## Dependencies
## Running Tests

```mermaid
flowchart TD
byjg/authuser --> byjg/micro-orm
byjg/authuser --> byjg/cache-engine
byjg/authuser --> byjg/jwt-wrapper
Because this project uses PHP Session you need to run the unit test the following manner:

```bash
./vendor/bin/phpunit --stderr
```

----
[Open source ByJG](http://opensource.byjg.com)
[Open source ByJG](https://opensource.byjg.com)
14 changes: 7 additions & 7 deletions composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -14,18 +14,18 @@
"minimum-stability": "dev",
"prefer-stable": true,
"require": {
"php": ">=8.3 <8.6",
"byjg/micro-orm": "^6.0",
"byjg/cache-engine": "^6.0",
"byjg/jwt-wrapper": "^6.0"
"php": ">=8.3 <8.7",
"byjg/micro-orm": "^7.0",
"byjg/cache-engine": "^7.0",
"byjg/jwt-wrapper": "^7.0"
},
"require-dev": {
"phpunit/phpunit": "^10.5|^11.5",
"vimeo/psalm": "^5.9|^6.13"
"phpunit/phpunit": "^12.5",
"psalm/phar": "^6.16"
},
"scripts": {
"test": "vendor/bin/phpunit",
"psalm": "vendor/bin/psalm --threads=1"
"psalm": "vendor/bin/psalm.phar"
},
"license": "MIT"
}
4 changes: 2 additions & 2 deletions docs/authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ if ($user !== null) {
```

:::tip Login Field
The `isValidUser()` method uses the login field configured in your `UsersService` constructor. Pass either `LoginField::Email` or `LoginField::Username` when creating the service.
The `isValidUser()` method uses the login field configured in your `UsersService` constructor. Pass `LoginField::Email`, `LoginField::Username` or `LoginField::EmailOrUsername` when creating the service.
:::
`LoginField` lives in the `ByJG\Authenticate\Enum` namespace.

Expand Down Expand Up @@ -75,7 +75,7 @@ if ($userToken !== null) {
}
```

Need to include standard user columns (name, email, etc.) automatically? Pass the optional seventh argument with `User` enum values or strings. See [JWT Tokens](jwt-tokens.md#copy-user-fields-automatically) for details.
Need to include standard user columns (name, email, etc.) automatically? Pass the optional seventh argument with `UserField` enum values or strings. See [JWT Tokens](jwt-tokens.md#copy-user-fields-automatically) for details.

:::tip UserToken Return Type
Both `createAuthToken()` and `createInsecureAuthToken()` return a `UserToken` object with three properties:
Expand Down
29 changes: 6 additions & 23 deletions docs/custom-fields.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,11 +41,11 @@ class CustomUserModel extends UserModel
string $email = "",
string $username = "",
string $password = "",
string $admin = "no",
string $role = "",
string $phone = "",
string $department = ""
) {
parent::__construct($name, $email, $username, $password, $admin);
parent::__construct($name, $email, $username, $password, $role);
$this->phone = $phone;
$this->department = $department;
}
Expand Down Expand Up @@ -186,6 +186,7 @@ You can mark fields as read-only to prevent updates using the `ReadOnlyMapper`:

```php
<?php
use ByJG\MicroOrm\MapperFunctions\NowUtcMapper;
use ByJG\MicroOrm\MapperFunctions\ReadOnlyMapper;
use ByJG\MicroOrm\Attributes\FieldAttribute;

Expand All @@ -212,41 +213,23 @@ You can transform fields during read/write operations using mappers. See [Mapper

### JSON Fields

For storing JSON data in custom fields:
For storing JSON data in custom fields, use a pair of mappers such as the `JsonEncodeMapper` / `JsonDecodeMapper` shown in [Mappers](mappers.md#json-columns-example):

```php
<?php
use ByJG\MicroOrm\FieldMapping\FieldHandler;
use ByJG\MicroOrm\Attributes\FieldAttribute;

class CustomUserModel extends UserModel
{
#[FieldAttribute(
fieldName: 'metadata',
updateFunction: [FieldHandler::class, 'toJson'],
selectFunction: [FieldHandler::class, 'fromJson']
updateFunction: JsonEncodeMapper::class,
selectFunction: JsonDecodeMapper::class
)]
protected ?array $metadata = null;
}
```

### Date/Time Fields

```php
<?php
use ByJG\MicroOrm\FieldMapping\FieldHandler;
use ByJG\MicroOrm\Attributes\FieldAttribute;

class CustomUserModel extends UserModel
{
#[FieldAttribute(
fieldName: 'created_at',
selectFunction: [FieldHandler::class, 'toDate']
)]
protected ?\DateTime $createdAt = null;
}
```

## Complete Example

```php
Expand Down
11 changes: 10 additions & 1 deletion docs/database-storage.md
Original file line number Diff line number Diff line change
Expand Up @@ -315,7 +315,7 @@ $propsRepo = new UserPropertiesRepository($db, CustomPropertiesModel::class);

## Login Field Configuration

You can configure whether users log in with their email or username:
You can configure whether users log in with their email, their username, or either of them:

### Login with Email

Expand All @@ -333,6 +333,15 @@ $users = new UsersService($usersRepo, $propsRepo, LoginField::Email);
$users = new UsersService($usersRepo, $propsRepo, LoginField::Username);
```

### Login with Username or Email

```php
<?php
$users = new UsersService($usersRepo, $propsRepo, LoginField::EmailOrUsername);
```

The login is looked up as a username first and, if no user is found, as an email.

:::tip Login Field
The login field affects methods like `isValidUser()` and `getByLogin()`. They will use the configured field for authentication.
:::
Expand Down
Loading
Loading