README

PHP client for metolabs-satcfdi-bridge, a stable JSON CLI interface on top of python-satcfdi.

The package communicates with satcfdi-bridge exec through stdin/stdout using Symfony Process. Secrets such as the e.firma private-key password are sent through stdin as part of the JSON request and are never placed in the process argument list.

Requirements

PHP 8.2+
metolabs-satcfdi-bridge installed and available in PATH
Symfony Process 7.4

Install the Python bridge first:

python3 -m venv /opt/satcfdi
/opt/satcfdi/bin/pip install metolabs-satcfdi-bridge

Then install this package:

composer require metolabs/satcfdi-php

CSF

use MetoLabs\SAT\Cfdi\Client;
use MetoLabs\SAT\Cfdi\Credentials\Fiel;

$fiel = Fiel::fromFiles(
    certificate: '/secure/fiel.cer',
    privateKey: '/secure/fiel.key',
    password: $password,
);

$client = Client::usingBridge('/opt/satcfdi/bin/satcfdi-bridge');

$artifact = $client->csf()->download(
    fiel: $fiel,
    destination: '/tmp/csf.pdf',
);

To obtain the PDF bytes directly:

$pdf = $client->csf()->contents($fiel);

Compliance Opinion (32-D)

$artifact = $client->compliance()->download(
    fiel: $fiel,
    destination: '/tmp/opinion.pdf',
);

or:

$pdf = $client->compliance()->contents($fiel);

Credentials from memory

When credentials come from object storage, a database, or Laravel Storage, the wrapper can create secure temporary files with directory permissions 0700 and file permissions 0600:

$fiel = Fiel::fromContents(
    certificate: $certificateContents,
    privateKey: $privateKeyContents,
    password: $password,
);

$pdf = $client->csf()->contents($fiel);

Temporary credentials are removed in finally blocks.

Generic operations

Convenience resources do not limit the bridge. Any registered bridge operation can be invoked directly:

$response = $client->execute('portal.rfc_valid', [
    'rfc' => 'AAA010101AAA',
]);

$result = $response->result;

This is useful when a new satcfdi-bridge operation is released before a dedicated PHP resource is added.

Portal helpers

$client->portal()->validateRfc('AAA010101AAA');
$client->portal()->validateLegalName('AAA010101AAA', 'ACME SA DE CV');
$client->portal()->lcoDetails('AAA010101AAA');

Capabilities

$capabilities = $client->capabilities();

if ($client->supports('csf.download')) {
    // Supported by the installed bridge.
}

Error handling

use MetoLabs\SAT\Cfdi\Exceptions\InvalidCredentialsException;
use MetoLabs\SAT\Cfdi\Exceptions\SatCfdiException;
use MetoLabs\SAT\Cfdi\Exceptions\UpstreamException;

try {
    $pdf = $client->csf()->contents($fiel);
} catch (InvalidCredentialsException $e) {
    // Invalid e.firma certificate, private key, or password.
} catch (UpstreamException $e) {
    // SAT/upstream/network error.
} catch (SatCfdiException $e) {
    // Other bridge or protocol error.
}

Security model

The executable receives only exec in argv:

satcfdi-bridge exec

Credential passwords and request payloads are written to the process stdin. They do not appear in ps aux command-line arguments. The package also keeps bridge diagnostics separate from the JSON protocol.

For file-based credentials, the wrapper reads the original files without copying them. For in-memory credentials, it uses a temporary private workspace and removes it after the operation.

Versioning

This library follows Semantic Versioning. The bridge JSON protocol is independently versioned. Version 1.x of this package currently speaks bridge schema 1.0.

Publishing

Create a public GitHub repository named MetoLabs/satcfdi-php, push master, and submit the repository to Packagist as metolabs/satcfdi-php. Packagist will read the package name and metadata from composer.json.

License

MIT.

metolabs / satcfdi-php

Maintainers

Package info

Statistics

Security