How eclipxe13/sat-ws-descarga-masiva works
Main Components and Their Roles
• Service Facade: The central “Service” class (located in src/Service.php) serves as the main entry point that ties together the process flow. It takes in a RequestBuilder and a WebClient.
• Web Client: Represent the component under src/WebClient (e.g., GuzzleWebClient) which implements WebClientInterface. This client is responsible for performing the HTTP/HTTPS communications with the SAT servers.
• Service Operations: Under src/Services, distinct namespaces for different functionalities exist:
• Authenticate – for handling token generation via FIEL based authentication.
• Query – for presenting the service request with parameters (using classes like QueryParameters).
• Verify – to check the status of a previously submitted request.
• Download – for retrieving the ZIP packages from the SAT.
• Package Readers: The functionality for processing downloaded packages is encapsulated in the PackageReader folder. Two major readers exist – CfdiPackageReader for CFDI XML packages and MetadataPackageReader for metadata ZIP packages.
• Internal Helpers: Various helper traits and classes (src/Internal, src/PackageReader/Internal) are used to encapsulate common logic like XML interactions, file filtering, and data manipulation.
Relationships and Data Flow
• This RequestBuilder is then passed, together with a configured WebClient (GuzzleWebClient), into the Service facade.
• The Service orchestrates:
• Authentication: using the FIEL via the RequestBuilder to obtain a Token.
• Query: the Service accepts a QueryParameters object (built using Shared types and RequestBuilder) and sends a signed request to SAT.
• Verification: after query submission, the client polls (or is informed through a verification call) the status of the request.
• Download: the Service then accepts package identifiers to retrieve ZIP packages.
• Package Readers: Once downloaded, these packages are parsed through the respective PackageReader classes to extract either CFDI XML files or metadata.
• Data flows from domain objects (the input parameters) to SOAP messages and back as response packages. Exceptions at any layer (e.g., in web communication or file operations within PackageReaders) should be represented as error flows back to the client.
Architectural Patterns / Design Principles
• Separation of Concerns: The library separates the responsibility of request creation (RequestBuilder), communication (WebClient), process orchestration (Service), and package processing (PackageReader).
• Interface-Based Design: Use of interfaces like RequestBuilderInterface and WebClientInterface allows for flexible, interchangeable implementations.
• Domain Modeling: The use of shared classes (e.g., DateTimePeriod, DocumentStatus, DownloadType, etc.) indicates a clear domain-driven design where business rules encapsulate the logic.
Relevant Technologies and Libraries
• PHP (as the main language).
• Composer (dependency management).
• Guzzle (for HTTP communication) as an example of WebClient use.
• SOAP-based communication (for interacting with SAT services).
• ZIP file manipulation for processing attachments.
• Optionally, mention integration with external packages (e.g., phpcfdi/credentials) for FIEL management.