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
1 change: 1 addition & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
* text=auto eol=lf

/.github export-ignore
/bin export-ignore
/tests export-ignore
/js/tests export-ignore
/.gitattributes export-ignore
Expand Down
8 changes: 8 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,12 @@ npm install @entity/keyring

The [changelog](CHANGELOG.md) lists what each release changes, and the [upgrade guide](UPGRADE.md) covers anything you need to do when updating.

## What's Stable

What the docs describe is what a release keeps to: the config options, the route names and paths, the middleware aliases, the `Keyring` facade and `Keyring::for($user)`, the factor and policy builders, the contracts in `Keyring\Contracts`, the events and their properties, the email types and what each is passed, the security log's entry types, the commands and their options, the testing helpers, and the browser package's exports. A change to any of those is called out in the [upgrade guide](UPGRADE.md), and before 1.0 a minor release (0.2, 0.3) may make one.

Everything else in `src/` is how Keyring does it and can change in any release: controllers, pipeline steps' internals, and anything in `Keyring\Support`. If you find yourself extending one of those, [Extending Keyring](docs/extending.md) probably has a supported way, and an issue is welcome when it doesn't.

## Security Vulnerabilities

Please don't open a public issue for a security problem. See the [security policy](SECURITY.md) for how to report one.
Expand All @@ -109,6 +115,8 @@ composer check # everything CI runs: Rector (dry run), Pint, PHPStan and Pes

Run `composer check` before opening a pull request.

`bin/ci` runs every job the GitHub workflow does on your own machine: the checks above, the oldest dependencies Keyring allows, PostgreSQL, MySQL (in Docker) and the browser package. `bin/ci tests js` runs only the jobs you name. Run one at a time.

The race tests run operations in separate processes against a real database, so they need PostgreSQL or MySQL and run as their own suite (CI runs them on both):

```bash
Expand Down
2 changes: 2 additions & 0 deletions UPGRADE.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
# Upgrade Guide

Keyring has no tagged release yet, so there's nothing to upgrade from. This guide starts with the first release, and will list anything you need to change when updating from one release to the next.

What counts as a change you'd need to act on is in the README's [What's Stable](README.md#whats-stable). A test (`tests/Feature/PublicApiTest.php`) fails when a route, middleware alias, facade method, contract, event or email type is renamed or removed, so one can't change without an entry here.
118 changes: 118 additions & 0 deletions bin/ci
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
#!/usr/bin/env bash
#
# Everything .github/workflows/tests.yml runs, on this machine: for when
# GitHub can't run it, or before pushing.
#
# bin/ci every job
# bin/ci tests js only the jobs named: tests, lowest, pgsql, mysql, js
#
# PostgreSQL is whichever server these point at (the workflow's own values
# unless set): PGHOST, PGPORT, PGUSER, PGPASSWORD, PGDATABASE. The database
# has to exist. MySQL is started in Docker for the run, on MYSQL_PORT (3307),
# bound to this machine only.
#
# One run at a time: the installer's tests publish into the test app every
# run shares, so two at once fail each other.

set -uo pipefail
cd "$(dirname "$0")/.."

jobs=("$@")
[ ${#jobs[@]} -eq 0 ] && jobs=(tests lowest pgsql mysql js)

failed=()

step() {
printf '\n\033[1m▸ %s\033[0m\n' "$*"
"$@" || return 1
}

tests() {
step composer audit --abandoned=report &&
step vendor/bin/rector --dry-run &&
step vendor/bin/pint --test &&
step vendor/bin/phpstan analyse --no-progress &&
step vendor/bin/phpstan analyse -c phpstan.stubs.neon --no-progress &&
step vendor/bin/pest --compact
}

# The oldest versions composer.json allows, in a copy, so this checkout's
# vendor directory and lock file stay as they are.
lowest() {
local copy index
copy=$(mktemp -d) && index=$(mktemp -u) || return 1

GIT_INDEX_FILE=$index git read-tree HEAD &&
GIT_INDEX_FILE=$index git checkout-index -a --prefix="$copy/" &&
(
cd "$copy" &&
step composer remove --dev calebdw/phpstan-laravel --no-update --no-interaction --quiet &&
step composer update --prefer-lowest --prefer-stable --no-interaction --prefer-dist --quiet &&
step vendor/bin/pest --compact
)
local status=$?

rm -rf "$copy" "$index"

return $status
}

database() {
step vendor/bin/pest --compact && step vendor/bin/pest --compact --testsuite=Concurrency
}

pgsql() {
DB_CONNECTION=pgsql DB_HOST=${PGHOST:-127.0.0.1} DB_PORT=${PGPORT:-5432} DB_DATABASE=${PGDATABASE:-keyring} \
DB_USERNAME=${PGUSER:-postgres} DB_PASSWORD=${PGPASSWORD-password} database
}

mysql() {
local name=keyring-ci-mysql port=${MYSQL_PORT:-3307}

docker run -d --rm --name "$name" -e MYSQL_DATABASE=keyring -e MYSQL_ROOT_PASSWORD=password \
-p "127.0.0.1:$port:3306" mysql:8.4 >/dev/null || return 1

# It answers a ping before it takes connections, so ask it a question.
for _ in $(seq 60); do
docker exec "$name" mysql -ppassword -e 'select 1' keyring >/dev/null 2>&1 && break
sleep 2
done

DB_CONNECTION=mysql DB_HOST=127.0.0.1 DB_PORT=$port DB_DATABASE=keyring DB_USERNAME=root DB_PASSWORD=password database
local status=$?

docker stop "$name" >/dev/null

return $status
}

js() {
(
cd js &&
step bun install --frozen-lockfile &&
step bun audit &&
step bun run typecheck &&
step bun test --randomize
)
}

for job in "${jobs[@]}"; do
case $job in
tests | lowest | pgsql | mysql | js)
printf '\n\033[1;34m━━ %s ━━\033[0m\n' "$job"
$job || failed+=("$job")
;;
*)
echo "Unknown job: $job. Pick from: tests, lowest, pgsql, mysql, js." >&2
exit 2
;;
esac
done

echo
if [ ${#failed[@]} -gt 0 ]; then
printf '\033[1;31mFailed: %s\033[0m\n' "${failed[*]}"
exit 1
fi

printf '\033[1;32mPassed: %s\033[0m\n' "${jobs[*]}"
55 changes: 55 additions & 0 deletions tests/Feature/PublicApiTest.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
<?php

declare(strict_types=1);

use Illuminate\Support\Facades\File;
use Illuminate\Support\Str;
use Keyring\Features;
use Keyring\KeyringManager;
use Keyring\UserKeyring;

// What apps build on, as the README's "What's Stable" lists it: the route
// names, the middleware aliases, the methods of the Keyring facade and of
// Keyring::for($user), the contracts, the events and the email types. A
// rename here breaks every app that uses it, and nothing else would notice
// when the tests are renamed with it.
//
// A change that's meant: run UPDATE_PUBLIC_API=1 vendor/bin/pest
// tests/Feature/PublicApiTest.php, commit tests/Fixtures/public-api.json
// with it, and say so in UPGRADE.md.
it('keeps the names apps build on, or says which changed', function () {
withFeatures(Features::all());

$methods = fn (string $class) => collect(new ReflectionClass($class)->getMethods(ReflectionMethod::IS_PUBLIC))
->reject(fn (ReflectionMethod $method) => $method->isConstructor() || Str::startsWith($method->getName(), '__'))
->map(fn (ReflectionMethod $method) => $method->getName())
->sort()->values()->all();

$classes = fn (string $directory, string $namespace) => collect(File::allFiles(__DIR__.'/../../src/'.$directory))
->map(fn (SplFileInfo $file) => $namespace.'\\'.str_replace('/', '\\', Str::beforeLast($file->getRelativePathname(), '.php')))
->sort()->values();

$api = [
'routes' => collect(app('router')->getRoutes()->getRoutes())
->filter(fn ($route) => $route->getName() !== null)
->mapWithKeys(fn ($route) => [$route->getName() => implode('|', array_diff($route->methods(), ['HEAD'])).' /'.ltrim($route->uri(), '/')])
->sortKeys()->all(),
'middleware' => collect(app('router')->getMiddleware())->keys()->filter(fn (string $alias) => Str::startsWith($alias, 'keyring'))->sort()->values()->all(),
'features' => Features::all(),
'emails' => KeyringManager::NOTIFICATIONS,
'facade' => $methods(KeyringManager::class),
'user' => $methods(UserKeyring::class),
'contracts' => $classes('Contracts', 'Keyring\\Contracts')->mapWithKeys(fn (string $contract) => [$contract => $methods($contract)])->all(),
'events' => $classes('Events', 'Keyring\\Events')->mapWithKeys(fn (string $event) => [
$event => collect(new ReflectionClass($event)->getProperties(ReflectionProperty::IS_PUBLIC))->map->getName()->sort()->values()->all(),
])->all(),
];

$path = __DIR__.'/../Fixtures/public-api.json';

if (getenv('UPDATE_PUBLIC_API')) {
File::put($path, json_encode($api, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_THROW_ON_ERROR)."\n");
}

expect($api)->toEqual(json_decode(File::get($path), true, flags: JSON_THROW_ON_ERROR));
});
Loading
Loading