Download the PHP package oliverbj/cord without Composer

Seamless integration to CargoWise One's eAdapter using Laravel

Cord offers an expressive, chainable API for interacting with CargoWise One's eAdapter over HTTP.

Table of Contents

• Support
• Installation
• Laravel Boost
• Configuration
• Usage
  • Operation Schemas
  • Targets
  • Request context
• Documents / eDocs
  • Upload documents
  • Add events
• DocManager
  • Fetch documents
• Organizations
  • Query Organization
  • Create Organization
  • Update Organization
  • Add an address
  • Add a contact
  • Add EDI communication details
  • Transfer existing organization data
• Company
  • Query Company
• Staff
  • Query Staff
  • Create Staff
  • Update Staff
• One Off Quotes
  • Query One-Off Quote
  • Create One-Off Quote
• Multiple Connections
• Raw XML
• Response as JSON
• Response as XML
• Field Selection
• Debugging
• Testing
  • Manual staff test

Support

Cord currently targets:

• PHP 8.2+
• Laravel 11 and 12

Installation

Install the package via Composer:

Publish the config file:

Laravel Boost

If your application uses Laravel Boost, Cord ships package-owned Boost resources so Boost can include Cord guidance automatically.

• Cord includes a core guideline that covers configuration, request flow, response handling, and package conventions.
• Cord also includes an optional cord-development skill for on-demand help with describe(), schema(), fromStructured(), inspect(), toJson(), toXml(), and rawXml().

In the consuming Laravel application:

After updating Cord or Boost itself, refresh generated agent resources with:

Boost discovers these resources from the package automatically, so Cord does not require an extra publish step beyond Boost's normal install and update commands.

Configuration

The published config/cord.php file looks like this:

Set your CargoWise eAdapter credentials in .env:

Usage

Start with a target, call get() before run() for organization, staff, and one-off quote retrievals, then execute the request with run(). By default Cord returns the decoded eAdapter payload as an array. Call toJson() or toXml() before run() when you need serialized output.

Operation Schemas

Cord now exposes AI-facing operation contracts and structured execution helpers.

describe() is registry-backed:

• Cord::describe() lists all published resources and operation ids.
• Cord::staff()->describe() lists the operations for the selected resource.
• Cord::staff('OJ0')->get()->describe() returns the active JSON-Schema-style contract for staff retrieval.
• Cord::staff()->create()->describe() returns the active JSON-Schema-style contract for that fully scoped builder.

Targets

Cord currently supports these main targets:

• Bookings via booking()
• Shipments via shipment()
• One-off quotes via oneOffQuote()
• Customs declarations via custom()
• DocManager documents via docManager()
• Organizations via organization()
• Companies via company()
• Containers via container()
• Staff via staff()
• Receivables / invoices via receivable() or receiveable() for document requests

Request context

You can scope a request to a specific CargoWise company:

For universal requests, withCompany() also enables Cord to derive a SenderID from the configured eAdapter host plus the company code, for example DEMO1TRNCPH. The default RecipientID is Cord.

If you need to override either value, you can set them explicitly:

Documents / eDocs

Most entities in CargoWise One expose eDocs. Use withDocuments() to retrieve a document collection for the selected target.

When fetching documents you can add filters:

Available filters:

• DocumentType retrieves only documents matching the specified document type.
• IsPublished retrieves only published or unpublished documents. Valid values are true and false.
• SaveDateUTCFrom retrieves only documents added or modified on or after the specified UTC timestamp.
• SaveDateUTCTo retrieves only documents added or modified on or before the specified UTC timestamp.
• CompanyCode retrieves only documents related to the specified company, or non-company-specific documents.
• BranchCode retrieves only documents related to the specified branch.
• DepartmentCode retrieves only documents related to the specified department.

For document lookups that are keyed by a CargoWise module code plus job number instead of a first-class Cord target, use DocManager.

Upload documents

You can upload a document to a CargoWise file with addDocument():

Document uploads are sent as UniversalEvent requests. When withCompany() is provided, Cord places Company, EnterpriseID, and ServerID inside Event > DataContext instead of using top-level interchange identifiers.

Add events

Cord can also push events to jobs:

addEventContext() appends Event > ContextCollection > Context rows.

Structured equivalent:

DocManager

Cord also supports CargoWise DocManager lookups for document collections that are keyed by a module code plus job number.

Fetch documents

Call withCompany() and pass the module code and job number separately. Cord composes the outgoing DataTarget > Key as <MODULE> <JOBNUMBER> for you and sends a UniversalDocumentRequest with Company, EnterpriseID, and ServerID inside DocumentRequest > DataContext.

Structured equivalent:

You can chain the same document filters used by withDocuments() before run() or inspect():

When CargoWise expects multiple distinct <FilterCollection> nodes, call filterCollection() once per collection:

Structured equivalent:

Introspection:

Requirements:

• withCompany(...)
• docManager($module, $key) with the CargoWise module code and job number
• Use filter() for a single FilterCollection, or filterCollection() / structured filter_collections when the request needs multiple distinct FilterCollection nodes.

Most used codes

Organizations

Cord maps beautifully into the organization module of CargoWise.

Query Organization

Use organization() with one or more criteriaGroup() calls for native organization queries, then call get() before run().

If the caller needs the organization payload as JSON instead of the default array, call toJson() before run():

The type argument can be either Key or Partial. Key is the default.

Partial Match Retrieval

You can retrieve entities by providing field names along with either complete values or partial values using wildcards to filter by. Multiple criteria items can be provided and multiple groups of criteria can be provided.

All items within a criteria group assume an ‘And’ operation, whilst an ‘Or’ operation is performed between each criteria group.

You can define multiple criteria groups. Multiple groups behave like an OR statement:

Unique Key Based Retrieval

This is the retrieval of data by providing a candidate key (unique reference). This message requires that the Code property on the table OrgHeader is a candidate key to work.

If you specify a FieldName that is not a candidate key, a Rejection status will be returned with an appropriate error message.

When using unique key based retrieval, only a single key can be specified. There will only be one Criteria element, as multiple criteria with different unique keys would never return a result. This is because you could never find an Organization with a code of ABC and XYZ

You can define multiple criteria groups. Multiple groups behave like an OR statement:

Create Organization

New organizations are created with organization('CODE')->create(). Supply at least fullName() — all other setters are optional. Multiple addresses and contacts can be chained.

Note: addAddress() and addContact() use the same builders as the update path. See Add a contact.

Update Organization

Native organization updates are anchored on organization('CODE')->update(). Call update() before any write setter — this mirrors the staff()->update() pattern.

Add an address

Required: code, addressOne, country, city.
Use ->capability($addressType, $isMainAddress) to append an address type. Call it multiple times for multiple capabilities.

Available setters: code, addressOne, addressTwo, country, city, state, postcode, relatedPort, phone, fax, mobile, email, dropModeFCL, dropModeLCL, dropModeAIR, active, capability.

Add a contact

Required: name, email.
Available setters: name, email, active, notifyMode, title, gender, language, phone, mobilePhone, homePhone, attachmentType.

Add EDI communication details

Required: module, purpose, direction, transport, destination, format.
Optional setters: subject, publishMilestones, senderVAN, receiverVAN, filename.

Transfer existing organization data

The transfer helpers copy an existing entity from a source organization payload to a target organization. They still accept a raw array sourced directly from a CargoWise payload:

• transferAddress()
• transferContact()
• transferEDICommunication()
• transferDocumentTracking()

Schema and structured execution

All organization write operations are registered in the operation registry, so fromStructured() and schema() work the same way as for One-Off Quotes and Staff:

Company

You are able to use Cord to interact with companies in CargoWise.

Query Company

Company queries follow the same native query pattern:

Staff

You can also use Cord to manage Staff records in CargoWise.

Container

Cord supports querying CargoWise container types via the native request pattern.

Query Container

Container queries use GlbContainerType as the criteria entity. Call get() before inspect() or run().

If you already know the container code, container('20GP')->get() preloads the same key criteria group.

Structured container queries work the same way:

Staff

You can also use Cord to manage Staff records in CargoWise.

Query Staff

Staff queries follow the same native criteria-group pattern as organization queries, but use GlbStaff as the criteria entity. Call get() before inspect() or run().

If you already know the staff code, staff('BVO')->get() preloads the same key criteria group for you.

Method introspection:

Create Staff

Staff creation is sent as a native Native request. Company context is required. EnterpriseID and ServerID are derived from the configured url, and CodesMappedToTarget defaults to true. You can override the native context with withEnterprise(), withServer(), or withCodeMapping(false).

Common fluent setters:

• code, loginName, password, fullName, branch, department, and country are required for create requests.
• withCompany('CPH') is required for native staff create/update requests.
• password(...) automatically sets ChangePasswordAtNextLogin to true.
• canLogin(...) maps to CargoWise CanLogin. Create payloads default to true when omitted; update payloads only include it when you set it.
• new staff create payloads automatically include IsOperational=true.
• replaceGroups([...]), addGroup(...), and removeGroup(...) are available for explicit group semantics.
• withPayload([...]) can be used as a passthrough for CargoWise fields not yet wrapped by dedicated methods.
• toPayload() returns the compiled staff payload without sending a request.

Method introspection:

schema() returns a JSON-Schema-style contract with properties, required, nested items, enums, and x-cord metadata for the operation id, resource, and action.

Update Staff

Staff updates are sent as native Native requests with Action="UPDATE".

One Off Quotes

Use Cord to interact with the One-Off Quote module in CargoWise.

Query One-Off Quote

One-off quote retrieval uses the universal shipment request with DataTarget Type="OneOffQuote" and a quote key.

Call withCompany() before run() so Cord can populate the One-Off Quote DataContext with the company, EnterpriseID, ServerID, and the ORP recipient role expected by CargoWise.

One-off quote query introspection:

Create One-Off Quote

One-off quote creation is sent as a universal shipment request with DataTarget Type="OneOffQuote".

Call withCompany() before run() so Cord can populate the create payload with the company, required quote branch(), optional orgRole(), EnterpriseID, ServerID, and any optional eventBranch() / eventDepartment() codes.

The address setters accept either a full nested address builder or a CargoWise organization code string such as ABSDEOSLP.

Structured one-off quote create payloads support the same shortcuts:

One-off quote create requirements:

• withCompany(...)
• branch(...)
• department(...)
• transportMode(...)
• portOfOrigin(...)
• portOfDestination(...)

Optional one-off quote create helpers:

• branch(...) maps to both Shipment > DataContext > Branch > Code and Shipment > JobCosting > Branch > Code.
• orgRole(...) maps to Shipment > OrgRole; use LOC for Local Client or OAG for Overseas Agent.
• packingMode(...) maps to Shipment > ContainerMode > Code; use values such as FCL, LCL, FTL, or LSE.
• commodity(...) maps to Shipment > LocalProcessing > Commodity > Code; passing a code such as GEN is sufficient.
• eventBranch(...) maps to Shipment > DataContext > EventBranch > Code.
• eventDepartment(...) maps to Shipment > DataContext > EventDepartment > Code.
• dataProvider(...) maps to Shipment > DataContext > DataProvider.
• carrierAddress(...) adds an organization address with AddressType set to ShippingLineAddress; passing a string such as DHLAIR_WW sets OrganizationCode to that carrier.
• overseasAgentAddress(...) adds an organization address with AddressType set to SendersOverseasAgent; passing a string such as MAIATLSAV sets OrganizationCode to that overseas agent.
• addPotentialCarrier(...) appends a PotentialCarrier row under PotentialCarrierCollection; passing KLMAIR_WW or LUFAIR_WW sets PotentialCarrier > Code to that organization code.
• addNote(...) appends a Note row under Shipment > NoteCollection; key(...) becomes Description, text(...) becomes NoteText, IsCustomDescription is always false, and NoteContext is fixed to AAA / Module: A - All; Direction: A - All; Freight: A - All.
• clientAddress(...), pickupAddress(...), deliveryAddress(...), carrierAddress(...), and overseasAgentAddress(...) accept either an address object or a plain organization code string.
• When passing an address object, address_line_1 is required unless address_override is set to true. With address_override: true, only city and country are required — useful for sending a partial address without a street line.
• In structured payloads, use org_role, packing_mode, commodity, event_branch, event_department, data_provider, carrier_address, overseas_agent_address, potential_carriers, notes, and either an address object or a plain string for the address fields.
• addPackLine(...) adds individual packing lines with pack_type (required), quantity (required), and optional weight, volume, length, width, and height. CargoWise one-off quote XML uses a shared dimension unit on LengthUnit, so Cord omits WidthUnit and HeightUnit from the outbound payload.
• In structured payloads, use notes as an array of objects with required key and text fields.
• In structured payloads, use pack_lines as an array of objects with pack_type, quantity, and dimension sub-objects such as weight => ['value' => 500, 'unit_code' => 'KG']. width and height accept the same input shape for consistency, but the generated XML keeps only the shared LengthUnit element.
• addContainer(...) adds individual containers with type (required, e.g. 20GP), optional count (defaults to 1), type_description, iso_code, and category (['code' => 'DRY', 'description' => 'Dry Storage']). Maps to ContainerCollection > Container in XML. Use this for FCL shipments.
• In structured payloads, use containers as an array of objects with type and the optional fields above.
• addChargeLine(...) adds individual charge lines. Required setters are chargeCode and description; optional setters are costAmount(value, currencyCode), sellAmount(value, currencyCode), chargeCodeGroup, branch, department, debtor, and displaySequence. Only the fields you provide appear in the outgoing XML — no rating behaviours, exchange rates, or posted flags are hard-coded. CargoWise eAdapter requires an ImportMetaData element on every charge line when importing; Cord adds <ImportMetaData><Instruction>INSERT</Instruction></ImportMetaData> automatically.
• In structured payloads, use charge_lines as an array of objects with charge_code, description, and optional cost_amount / sell_amount (each with value and currency_code), charge_code_group, branch, department, debtor, and display_sequence.

One-off quote introspection:

CargoWise does not support one-off quote updates through eAdapter, so Cord does not publish a one_off_quote.update operation.

Add Document to One-Off Quote

Add a document to an existing one-off quote with addDocument(). This uses UniversalEvent rather than UniversalShipment. Call withCompany() so Cord can populate Event > DataContext with Company, EnterpriseID, and ServerID for the target quote key.

Structured equivalent:

Add Event to One-Off Quote

Add an event to an existing one-off quote with addEvent(). This also uses UniversalEvent. Call withCompany() so Cord can populate Event > DataContext with Company, EnterpriseID, and ServerID for the target quote key.

Structured equivalent:

Multiple Connections

If you need to connect to multiple eAdapters, use withConfig():

Then add the additional connection to config/cord.php:

The configured URL does not have to point directly at the eAdapter itself. It can point to middleware, as long as that middleware forwards the request and returns the eAdapter response. If you want enterprise and server auto-detection for native write requests, the URL should preserve the CargoWise host pattern such as https://demo1trnservices.example.invalid/eAdaptor.

Raw XML

If you already have a complete XML payload and just want Cord to send it with the configured eAdapter credentials and headers, use rawXml():

For raw XML requests, run() returns the full parsed eAdapter envelope instead of only Data. That means Status, ProcessingLog, and Data are all preserved.

inspect() still performs a dry run and returns the outbound XML unchanged:

Response as JSON

If you want the same response payload serialized as JSON, call toJson() before run():

For rawXml() requests, toJson() returns the full response envelope as JSON, including Status, ProcessingLog, and Data:

Response as XML

If you want the original eAdapter response as XML, call toXml() before run():

For rawXml() requests, toXml() returns the full response envelope, including Status and ProcessingLog:

Field Selection

Chain select() before run() on any query to restrict the returned payload to just the fields you need:

select() works across all response types: flat single-record responses, multi-record lists, and universal shipment payloads. It also composes with toJson():

Debugging

Use inspect() to build and inspect the outgoing XML without sending the HTTP request:

Testing

composer test now covers both staff creation and non-collection staff updates.

Manual staff test

For controlled manual testing, Cord includes a local runner script that builds the staff payload and only sends it when you explicitly opt in. By default it creates staff; add --update to send an update instead.

1. Create a local .env from .env.example and fill in your connection details.
2. Copy resources/manual/staff-payload.example.php to resources/manual/staff-payload.local.php.
3. Edit the local payload file with the staff data you want to test.
4. Run an inspect-only dry run first:

That prints the exact XML and does not send anything.

When you are ready to post the request, run:

To update an existing staff row such as XX0, keep the code in your payload and add --update:

Example local .env:

The runner derives EnterpriseID=XXX and ServerID=TRN from that URL and uses them in the native DataContext.

You can still override the derived native context per run if needed:

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Oliver Busk
• All Contributors

License

The MIT License (MIT). Please see License File for more information.