Download the PHP package slash197/reges-laravel without Composer

reges-laravel

Laravel bridge for slash197/reges, the PHP client for the REGES Online API, the Romanian general register of employees run by Inspecția Muncii.

Status: 0.x. Verified against the REGES test environment, but the API of this package may still change before 1.0. See the changelog.

Reporting to REGES is not a single HTTP call. A submission is only queued; the outcome arrives later in a separate queue; a contract's messages must arrive in order; and the id REGES gives a new employee is needed before the contract can be sent. This package takes care of that part for a Laravel application:

• The client in the container, configured from config/reges.php, for one company or for one API key per tenant.
• An outbox. Messages are validated, stored, sent in order, retried on transient failures and matched to the result REGES reports later.
• Events for accepted, rejected and undeliverable messages, carrying your own model and context.
• A local copy of the nomenclators, so values are checked before a message is stored.
• Artisan commands to send, read results, refresh the nomenclators and check the setup.

What stays in your application is what only it knows: turning your employees and contracts into messages, deciding which operation a change amounts to, and what to do when a message is accepted or refused. Building messages, the 42 operations and the rules of the registry are described in the core package's README; read it alongside this one.

Contents

• Requirements
• Installation
• Quick start
• Configuration
• One registry or several
• Sending messages
• The stored message
• Reading results
• Nomenclators
• Commands
• Events
• Without the outbox
• Tokens, HTTP client and logging
• Personal data
• Testing your application
• Troubleshooting
• Contributing
• Development

Requirements

• PHP 8.2 or newer
• Laravel 12 or 13
• A database, for the outbox table (not needed if you switch the outbox off)
• A cache store that is shared between your processes, for access tokens and the nomenclator copy
• The scheduler running (php artisan schedule:work, or cron calling schedule:run)

Laravel's queue is not used.

Installation

The service provider and the Reges facade are discovered automatically. The migration creates one table, reges_messages.

Publish the config file if you want to change more than the environment variables allow, and the migration if you want to alter it:

Quick start

For one company, on the REGES test environment.

1. Credentials. REGES uses two sets: an OAuth client id and secret, the same for every integrator (the ones for the test environment are published in the official integration docs), and an API key pair per employer registry, generated in the REGES employer application under Setări → Acces → Chei API.

2. Check the setup and download the nomenclators.

3. Schedule the commands, in routes/console.php:

4. Queue a message where your application registers an employee:

5. Handle the outcome in listeners:

Within a minute or two the employee is in the registry and your model has its REGES id.

Configuration

Everything is driven by environment variables; the published config/reges.php holds a few more settings.

Who is sending. REGES records two identities with each message. The author is the API key. The user is a free-text name of the person in your application: pass it per message (user:), or set REGES_USER as the default. A message with neither is refused before it is stored.

Production. Set REGES_ENVIRONMENT=production and the client id and secret REGES issued for production. The production token URL in the core package was derived by analogy with the test one; if authentication fails there, set REGES_TOKEN_URL.

One registry or several

An API key belongs to exactly one employer registry. The bridge refers to a registry by a registry key, a string your application chooses.

One registry

With REGES_USERNAME and REGES_PASSWORD set there is one registry, called default, and you never need to name it. The client is in the container and behind a facade:

Several registries

A SaaS, a payroll bureau or a group of companies has one API key per company. Tell the bridge where the keys are by binding a CredentialsProvider; the registry key is then whatever identifies a company to you, typically its id:

Leave REGES_USERNAME and REGES_PASSWORD empty. Throw from credentials() for a company that has no key or has REGES switched off: queue() then fails for that company, and messages it already has in the outbox stay pending and are retried, so they go out once the key is back.

Pass the registry key wherever the bridge takes one, and get a client for a registry directly when you need it:

Things worth knowing:

• Store API keys encrypted, for example with Laravel's encrypted cast.
• Tokens are cached under a key derived from the token URL, the client id and the API username, so registries never share a token.
• A client is built once per registry key per request or command. After changing a company's key in a long-running process, call app(Registries::class)->forget().
• The OAuth client, the environment and the application name are the same for all registries.

Sending messages

Queueing

queue() validates the message, puts it in its final wire form and stores it. It makes no HTTP request, so it is safe to call inside a web request or a database transaction. It returns the stored message.

If the message lacks something its operation needs, or a value is not in the nomenclators, queue() throws and stores nothing:

Sequences

REGES processes messages in the order it receives them and refuses a contract's messages that arrive out of order. Messages queued with the same sequence are therefore sent one at a time, in the order they were queued, each waiting for the result of the one before.

• Use one sequence per employee and one per contract, for example "employee:{$id}" and "contract:{$id}". Sequences are per registry.
• A message carries the timestamp of the moment it was queued, and REGES compares those. Queue messages in the order the changes happened.
• A rejected, failed or cancelled message does not hold back the ones after it.
• Messages in different sequences, or with no sequence, do not wait for each other.

Messages that depend on an earlier result

A contract needs the REGES id of its employee, and a change to a contract needs the REGES id of the contract. Those ids only exist once the earlier message has been accepted, so queue the dependent message from your MessageAccepted listener:

What ref identifies depends on the operation: the new employee, the new contract, the new proposal, or the history entry a contract operation created. The table is in the core README.

Sending

reges:send sends every message that is due, oldest first, and reges:results records the outcomes. Schedule both every minute, as in the quick start. On the test environment a result typically arrives within a second or two of sending, so a message is usually resolved on the run after the one that sent it.

A message goes through these statuses:

Retries and failures

To send something again after a rejection, fix the data and queue a new message. A stored message is never rebuilt, since its timestamp and content are final.

The stored message

queue() returns a slash197\Reges\Laravel\Outbox\OutboxMessage, an Eloquent model, and the events carry the same model.

Give your own models the inverse relation to show the REGES state of a record:

A message that has not been sent yet can be withdrawn; cancel() returns false once it is too late:

Old messages are not pruned. Delete what you no longer need yourself, keeping in mind that the ref of an accepted message is the only record of that id unless you copied it to your own tables.

Reading results

reges:results reads the result queue of the configured registry and of every registry that has a message awaiting its result. For each result it dispatches a ResultReceived event; the outbox listens to it, matches the result to its stored message and dispatches MessageAccepted or MessageRejected.

You only need ResultReceived yourself to see every result, including those of messages your application did not send through the outbox:

Nothing is lost, and listeners may run twice. The queue moves past a result only after every listener has returned, including your MessageAccepted and MessageRejected listeners. If one throws, that registry's run stops, the exception is reported, and the same result is delivered again on the next run. Two consequences:

• write listeners so that handling the same outcome twice does no harm;
• a result whose listener always throws holds back the results behind it, so fix or catch such errors rather than letting them repeat.

A listener that implements ShouldQueue counts as done once it is on your queue.

Sharing a registry. Each reader of a registry's queue has its own position, identified by a consumer id. If another application, or another environment of yours, reads the same registry, give each its own REGES_CONSUMER_ID, or they take each other's results. A new consumer id starts from the beginning of the queue.

Options. --registry=KEY (repeatable) reads only the registries named, --consumer=ID overrides the consumer id, and --limit=N caps the results read per registry in one run.

Your own loop. ResultReader is what the command uses, if you want to read a queue from your own code:

Nomenclators

The nomenclators are the reference lists REGES validates against. With a local copy, the client checks three kinds of value before a message is stored or sent: country names, identity document types and locality (SIRUTA) codes.

• Until the first download those checks are skipped; everything else is still validated.
• The lists change, so refresh the copy on a schedule. An empty answer from REGES leaves the existing copy untouched.
• The nomenclators are public: the command works without an API key.
• The copy lives in the cache. php artisan cache:clear removes it, and the checks are skipped again until the next download. Set REGES_NOMENCLATOR_CACHE_STORE to a store you do not clear if that matters to you.
• To check against your own copy instead, bind slash197\Reges\Validation\NomenclatorLookup in the container.

Countries are referred to by name, spelled exactly as the nomenclator spells it (România, not Romania); most other fields take a code. To fill your own dropdowns, fetch any list through the client: Reges::nomenclators()->get('TemeiIncetare').

Commands

reges:send is registered only while the outbox is enabled. reges:results exits with a failure code if any registry could not be read, after reading the others.

Events

All in slash197\Reges\Laravel\Events.

Without the outbox

If your application already has its own way of storing and ordering messages, set REGES_OUTBOX=false. No table is created and reges:send is not registered. You still get the configured client, the registries, token caching, the nomenclator copy, reges:check and reges:results:

and match results in a ResultReceived listener by $event->result->messageId. With the outbox off, reges:results reads the configured registry, or the ones you name with --registry.

You can also mix the two: a message sent directly through the client simply has no stored counterpart, and its result reaches you through ResultReceived only.

Tokens, HTTP client and logging

Tokens. Access tokens are kept in the cache, encrypted with the application key, until they expire. To keep them elsewhere, implement slash197\Reges\Auth\TokenStore and bind it:

To build a single client with a store of its own, outside the registries, use the factory: app(RegesFactory::class)->make($credentials, $tokenStore).

HTTP client. Requests go through a Guzzle client with the timeouts from reges.http. If your application binds Psr\Http\Client\ClientInterface in the container, that client is used instead, and timeouts, proxies and retries are yours to configure on it.

Logging. The client logs one line per request to REGES_LOG_CHANNEL: method, endpoint, status and the request id REGES returns. Message contents are never logged.

Personal data

Messages to REGES carry CNPs, names and addresses, and so do its answers (a result reads, for example, "Salariatul … cu CNP … a fost adăugat cu succes"). The package therefore:

• encrypts payload, error and result_description in the outbox table with the application key;
• encrypts cached access tokens;
• never logs message contents.

Rotating APP_KEY makes stored messages unreadable unless you keep the old key in APP_PREVIOUS_KEYS. meta is stored as plain JSON, so do not put personal data in it. The exception messages the commands print and report can quote what REGES answered.

Testing your application

Outbox::queue() makes no HTTP request, and an outcome can be simulated by dispatching the result yourself, so most tests need no fake client at all.

Give the test environment an API username that is a UUID, because REGES identifies the author by it and the message is validated accordingly:

Assert that your code queued the right message:

Simulate the outcome and assert what your listeners did:

Any code other than SUCCES, with a description, simulates a rejection.

To exercise the HTTP layer as well, bind a fake PSR-18 client before anything resolves the REGES client, for example in setUp():

A mock that has run out of responses throws, which also guarantees that a test never reaches the real REGES.

Troubleshooting

Contributing

Issues and pull requests are welcome, including small ones: a bug report with the operation and what REGES answered is already useful. Please leave real CNPs, company codes and credentials out of issues, tests and commits.

Before opening a pull request, run make check. Tests must not reach the network; the test base class installs a fake HTTP client for that reason.

Questions about messages, operations and how REGES itself behaves belong in the core package.

Development

Nothing needs to be installed on the host besides Docker:

PHP_VERSION=8.4 make build switches the PHP version of the container.

Disclaimer

This is an independent, unofficial project. It is not affiliated with or endorsed by Inspecția Muncii. The official integration documentation lives at reges-ro/integrare.

Licence

MIT. See LICENSE.