davidlares/gs1-ai

A GS1 Application identifier wrapper for Laravel

v1.0.4 2026-04-17 22:00 UTC

Requires

• php: ^8.2
• illuminate/support: ^10.0|^11.0|^12.0

Requires (Dev)

• orchestra/testbench: ^9.0

MIT

• David E Lares S

README

This is a Laravel-based package designed to interact with an GS1 Application Identifiers API, providing structured DTOs, collections, and a rule-based engine for working with identifiers, validations, qualifiers, exclusions, and requirements.

What are GS1 Application Identifiers (AIs)?

GS1 Application Identifiers (AIs) are standardized numeric prefixes used in barcodes (like GS1-128, DataMatrix, QR codes) to define the meaning and format of the data that follows.

For example: (01)09506000134352

01 → AI (Global Trade Item Number - GTIN) and 09506000134352 → actual data

Each AI defines:

• What the data represents (e.g., product, batch, expiration date)
• The expected format (numeric, alphanumeric, fixed/variable length)
• Whether it requires validation (e.g., check digits)
• How it interacts with other AIs

This package helps you consume, structure, and reason about this metadata programmatically.

Features

• Clean DTO-based architecture
• Laravel-friendly Collection support
• Built-in GS1 API client
• Support for:
  • General identifier metadata
  • Validations
  • Requirements
  • Exclusions
  • Qualifiers
• Logical rule modeling (AND / OR conditions)
• Extensible and testable design
• Ready for caching & advanced parsing

Identifier general data

This is the associated specification for the identifier, it basically describes the identifier itself.

Field	Meaning
ai	Application Identifier code
title	Short name
description	Human-readable explanation
regex	Validation pattern
separator	Whether FNC1 separator is required
is_gs1_digital_link_pk	Can be used as Digital Link primary key
is_valid_for_data_attributes	Can act as attribute
note	Associated note to the identifier

Validation data

Defines how the data should be validated.

Field	Meaning
fixed_length	Must be exact length
is_optional	Field may be omitted
check_digit	Includes check digit
key	Primary key relevance
format	Special format rule
length	Expected length
type	Data type (N = numeric, X = alphanumeric)

Installation

Install via Composer:

composer require davidlares/gs1-ai

Setup

Run the install command:

php artisan gs1-ai:install

This will publish the configuration file:

config/gs1-ai.php

Configuration

Add your API URL in .env:

GS1_AI_API_URL=https://ai.concilier.app/api

Basic Usage

use Davidlares\GS1\AI\Facades\Identifier;

$identifier = Identifier::find('01');

Accessing General Information

$identifier->ai();
$identifier->description();
$identifier->title();
$identifier->regex();
$identifier->note();

Boolean Helpers

$identifier->containSeparator();
$identifier->containDigitalLinkQualifiers();

Validations

foreach ($identifier->validations as $validation) {
    $validation->length;
    $validation->fixed_length;
}

Helpers

$identifier->amountOfvalidators();

Exclusions / Requirements / Qualifiers

foreach ($identifier->exclusions as $rule) {
    $rule->ais();
    $rule->belongsToGroup();
}

DTO (Data Transfer Objects)

All API responses are converted into structured objects:

• Identifier
• General
• Validations
• Exclusions
• Requirements
• Qualifiers

This ensures:

• Type safety
• Clean access (-> instead of arrays)
• Extensibility

Collections

Array-based sections are converted into Laravel Collections:

$identifier->validations
$identifier->exclusions
$identifier->requirements
$identifier->qualifiers

This enables:

$identifier->validations->count();
$identifier->validations->first();

Rule Engine

Exclusions, Requirements, and Qualifiers are modeled as logical rules:

• String → single condition
• Array → grouped condition (AND)
• Top-level array → OR

Example:

["02", ["10", "21"]]

Meaning:

02 OR (10 AND 21)

Architecture

Identifier
 ├── General
 ├── Validations (Collection)
 │     └── Validation
 ├── Exclusions (Collection)
 │     └── Exclusion (Rule)
 ├── Requirements (Collection)
 └── Qualifiers (Collection)

Core Classes

Identifier

Main entry point.

Methods

• ai()
• description()
• title()
• regex()
• note()
• containSeparator()
• containDigitalLinkQualifiers()
• amountOfvalidators()

General

Represents metadata of an identifier.

Methods

• canBeDigitalLinkPK()
• isValidForDataAttributes()

Validation

Represents a validation rule.

Properties

• fixed_length
• is_optional
• check_digit
• length
• type

Exclusion / Requirement / Qualifier

Logical rule representation.

Methods

• ais() → returns involved AIs
• belongsToGroup() → indicates AND grouping

Testing

This package supports testing via:

• orchestral/testbench

Example setup:

composer require --dev orchestra/testbench

Run:

vendor/bin/phpunit .\tests\

Error Handling

You can use the built-in Laravel exception for this

Example:

try {
    Identifier::find('01');
} catch (\Exception $e) {
    // handle error
}

Credits

David Lares S

License

MIT