How whatarmy/fedexrest works
The project is a PHP library that provides a convenient wrapper for FedEx’s new Rest API services. It is not a full application per se but rather an integration library meant to simplify interaction with FedEx endpoints. The library is structured to support multiple service domains such as Shipping, Pickup, Tracking, Address Validation, Rates, and more. It is built using standard PHP project conventions (composer, PHPUnit for testing, and GitHub actions for CI), and uses object‐oriented design to encapsulate different functionalities.
Main Components
• Authorization Module – Found under src/FedexRest/Authorization, this handles the oAuth process (authorizing the client and caching the token).
• Entities – Located in src/FedexRest/Entity and subdirectories (e.g., Address, CustomerReference, DangerousGoodsDetail, etc.), these represent data structures exchanged among services.
• Services – The core function of the library is implemented here; each service group (like AddressValidation, LocationSearch, Pickup, Ship, Track, Rates) has its own set of classes and subcomponents.
– Each service is built upon a common abstraction (see AbstractRequest and RequestInterface) to standardize operations.
• Exceptions – Organized in src/FedexRest/Exceptions and under certain services (for example, in the Ship service), these define error conditions specific to each API.
• Utility and Traits – Additional helper classes in src (Utils.php) and traits (rawable.php; switchableEnv.php) provide shared functionality.
• Testing – The tests directory mirrors the structure of the src directory and clearly shows how each component is tested.
Relationships and Interactions
• The Authorization component is called by the service classes to obtain an access token (which is needed for every API request).
• Service classes use the Entity classes to build request payloads and parse responses.
• The AbstractRequest (and RequestInterface) defines common behavior and enforces consistency across different service implementations.
• Error-handling is done via dedicated Exception classes which are thrown when required parameters (like access token, account number, etc.) are missing.
• The library’s clients (e.g., user code) interact with each service by instantiating service classes and using setter methods that accept Entity objects.
• Testing modules in the tests directory show integration points and confirm the behavior of these interactions.
Architectural Patterns/Design Principles
• Encapsulation – Different API components (Ship, Track, Pickup, etc.) are encapsulated individually.
• Builder/Fluent Interfaces – Observe how the library uses a fluent interface (chainable setter methods) to configure requests.
• Inheritance/Abstraction – AbstractRequest and interface definitions ensure that services share common request behaviors.
• Dependency Inversion – The services depend on common contracts (RequestInterface) rather than concrete implementations.
Relevant Technologies and Frameworks
• PHP (object-oriented PHP, composer for dependency management)
• PHPUnit for testing of components
• GitHub Actions (via the workflow files in .github/workflows) for CI/CD
• The library connects with external FedEx Rest API endpoints.
Instructing the Principal Software Engineer
– Authorization (oAuth workflow)
– Entities (all data models, e.g., Address, Weight, etc.)
– Service Modules (group them by API, such as Ship, Track, Rate, Address Validation, etc.)
– Abstract Components (AbstractRequest, RequestInterface)
– Exception Handling (list the exception classes logically related to services)
– External FedEx Rest API (as an external system the library interacts with)
– From client code into the Library’s API service component.
– From Services to Authorization to obtain tokens.
– From Services to Entities as they build the payloads.
– From Services to external FedEx API (HTTP calls/response).