PHPackages                             ottosmops/beacon - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Parsing & Serialization](/categories/parsing)
4. /
5. ottosmops/beacon

ActiveLibrary[Parsing & Serialization](/categories/parsing)

ottosmops/beacon
================

A PHP library for parsing BEACON files

v0.1.1(9mo ago)02MITPHPPHP >=8.1CI passing

Since Aug 17Pushed 9mo agoCompare

[ Source](https://github.com/ottosmops/beacon)[ Packagist](https://packagist.org/packages/ottosmops/beacon)[ RSS](/packages/ottosmops-beacon/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (3)Versions (3)Used By (0)

[![CI](https://github.com/ottosmops/beacon/actions/workflows/ci.yml/badge.svg)](https://github.com/ottosmops/beacon/actions/workflows/ci.yml)[![codecov](https://camo.githubusercontent.com/57227766fcb659d83ce3bd854a4ec5e9084d7d35f74c28e8d178a9aa264232aa/68747470733a2f2f636f6465636f762e696f2f67682f6f74746f736d6f70732f626561636f6e2f6272616e63682f6d61696e2f67726170682f62616467652e737667)](https://codecov.io/gh/ottosmops/beacon)[![Total Downloads](https://camo.githubusercontent.com/1442c2ddb1aba1d553752fa3bb6b96bee25d5ab0f51f0d4d90ac9a184137edcf/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6f74746f736d6f70732f626561636f6e)](https://packagist.org/packages/ottosmops/beacon)[![License](https://camo.githubusercontent.com/23070fbef07734f64ca1795eb8ace75db4d756882a9b69540d2b764dceb7c3be/68747470733a2f2f706f7365722e707567782e6f72672f6f74746f736d6f70732f626561636f6e2f6c6963656e7365)](https://packagist.org/packages/ottosmops/beacon)[![Latest Stable Version](https://camo.githubusercontent.com/c788d4b154609925370508b881455320e7da8b873fd8c3bfecaacb32b9b501d8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6f74746f736d6f70732f626561636f6e)](https://packagist.org/packages/ottosmops/beacon)[![PHP Version Require](https://camo.githubusercontent.com/8d5a8230c01cedab79e6882f822c7689f7923bd59c9cb2157cae9a7d0abe1055/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6f74746f736d6f70732f626561636f6e)](https://packagist.org/packages/ottosmops/beacon)

BEACON Parser
=============

[](#beacon-parser)

A PHP library for parsing BEACON files.

**The package was heavily constructed with AI assistence. Please doublecheck if you want to use it in production.**

Overview
--------

[](#overview)

BEACON is a data interchange format for large numbers of uniform links. A BEACON file contains meta fields and links that can be used to create connections between different datasets.

This library provides a PHP implementation for parsing BEACON files according to the [BEACON specification](https://gbv.github.io/beaconspec/beacon.html).

Features
--------

[](#features)

- Parse BEACON files from strings or file paths
- Extract meta fields and link data
- Support for all BEACON meta fields (PREFIX, TARGET, MESSAGE, RELATION, etc.)
- Link construction with URI pattern expansion
- Validation of BEACON file format

Installation
------------

[](#installation)

Install via Composer:

```
composer require ottosmops/beacon
```

Quick Start
-----------

[](#quick-start)

### Basic Usage

[](#basic-usage)

```
use BeaconParser\BeaconParser;

// Parse from file
$parser = new BeaconParser();
$beaconData = $parser->parseFile('path/to/beacon.txt');

// Parse from string
$beaconContent = file_get_contents('beacon.txt');
$beaconData = $parser->parseString($beaconContent);

// Access meta fields
$description = $beaconData->getMetaField('DESCRIPTION');
$prefix = $beaconData->getMetaField('PREFIX');

// Access links
$links = $beaconData->getLinks();
foreach ($links as $link) {
    echo $link->getSourceIdentifier() . ' -> ' . $link->getTargetIdentifier() . "\n";
}
```

### Working with Links

[](#working-with-links)

```
// Get constructed links with full URIs
$links = $beaconData->getConstructedLinks();

foreach ($links as $link) {
    echo "Source: " . $link->getSourceIdentifier() . "\n";
    echo "Target: " . $link->getTargetIdentifier() . "\n";
    echo "Relation: " . $link->getRelationType() . "\n";
    if ($link->hasAnnotation()) {
        echo "Annotation: " . $link->getAnnotation() . "\n";
    }
    echo "---\n";
}
```

BEACON Format
-------------

[](#beacon-format)

BEACON files consist of:

1. Format indicator (`#FORMAT: BEACON`)
2. Meta fields (lines starting with `#`)
3. Empty lines (optional)
4. Link lines

### Example BEACON File

[](#example-beacon-file)

```
#FORMAT: BEACON
#PREFIX: http://example.org/
#TARGET: http://example.com/
#DESCRIPTION: Example link dump
#CREATOR: Example Organization

alice|About Alice
bob||http://example.net/bob
charlie|Charlie's Page|http://example.net/charlie

```

Meta Fields
-----------

[](#meta-fields)

The library supports all standard BEACON meta fields:

### Link Construction Fields

[](#link-construction-fields)

- `PREFIX` - URI pattern for source identifiers
- `TARGET` - URI pattern for target identifiers
- `MESSAGE` - Default link annotation
- `RELATION` - Relation type for links
- `ANNOTATION` - Meaning of link annotations

### Link Dump Description Fields

[](#link-dump-description-fields)

- `DESCRIPTION` - Human readable description
- `CREATOR` - Creator name or URI
- `CONTACT` - Contact information
- `HOMEPAGE` - Website with additional information
- `FEED` - Download URL
- `TIMESTAMP` - Last modification date
- `UPDATE` - Update frequency

### Dataset Fields

[](#dataset-fields)

- `SOURCESET` - Source dataset URI
- `TARGETSET` - Target dataset URI
- `NAME` - Target dataset name
- `INSTITUTION` - Responsible organization

Link Construction
-----------------

[](#link-construction)

The library automatically constructs full URIs from link tokens using the meta fields:

- Source identifiers are constructed using the `PREFIX` pattern
- Target identifiers are constructed using the `TARGET` pattern
- Default values are applied when tokens are missing
- URI patterns support `{ID}` and `{+ID}` expansions

Validation
----------

[](#validation)

The library includes a validator to check BEACON files.

### Using the Validator

[](#using-the-validator)

```
use BeaconParser\BeaconParser;

$validator = new BeaconValidator();

// Validate from file
$result = $validator->validateFile('beacon.txt');

// Validate from string
$result = $validator->validateString($beaconContent);

// Check if valid
if ($result->isValid()) {
    echo "BEACON file is valid!\n";
} else {
    echo "BEACON file has errors:\n";
    foreach ($result->getErrors() as $error) {
        echo "- $error\n";
    }
}

// Show detailed report
echo $result->getDetailedReport();
```

### CLI Validation Tool

[](#cli-validation-tool)

A command-line validation tool is included that supports both local files and URLs:

```
# Validate a local BEACON file
php bin/validate-beacon.php example.beacon

# Validate a BEACON file from URL
php bin/validate-beacon.php https://example.org/beacon.txt

# Validate with full path
php bin/validate-beacon.php /path/to/beacon/file.txt

# Show help
php bin/validate-beacon.php --help
```

The CLI tool automatically detects whether the input is a URL (starting with `http://` or `https://`) or a local file path and handles the validation accordingly.

#### URL Validation Features

[](#url-validation-features)

- **Automatic URL Detection**: Recognizes HTTP/HTTPS URLs automatically
- **Secure Downloads**: Uses proper HTTP headers and timeout handling
- **Error Handling**: Provides clear error messages for HTTP errors (404, 500, etc.)
- **Content Type Support**: Accepts text/plain and other text formats

### Validation Features

[](#validation-features)

The validator checks for:

- **File Structure**: Format indicator, proper line endings, UTF-8 encoding
- **Meta Fields**: Known fields, proper syntax, valid values
- **URI Validation**: Valid URIs in appropriate fields
- **Link Construction**: Proper token handling and URI building
- **Best Practices**: Recommended fields, HTTPS usage, proper formatting
- **Specification Compliance**: Full adherence to BEACON specification

Exit codes:

- `0`: File is valid
- `1`: File has validation errors
- `2`: File not found or other error

Usage Examples
--------------

[](#usage-examples)

### CLI Usage Examples

[](#cli-usage-examples)

```
# Validate local files
php bin/validate-beacon.php example.beacon
php bin/validate-beacon.php /path/to/beacon/file.txt

# Validate remote files from URLs
php bin/validate-beacon.php https://example.org/beacon.txt
php bin/validate-beacon.php http://data.example.com/links.beacon

# Show detailed help
php bin/validate-beacon.php --help
```

### Programming Examples

[](#programming-examples)

### Example BEACON File

[](#example-beacon-file-1)

```
## Examples

### Sample BEACON File

```beacon
#FORMAT: BEACON
#PREFIX: http://example.org/people/
#TARGET: http://example.com/documents/
#DESCRIPTION: Example BEACON file mapping people to documents
#CREATOR: Example Organization
#RELATION: http://purl.org/dc/elements/1.1/contributor

alice
bob|author
charlie|editor|special-doc
diana||http://example.net/external-doc

```

### Parsing Example

[](#parsing-example)

```
use BeaconParser\BeaconValidator;

$parser = new BeaconParser();
$beaconData = $parser->parseFile('example.beacon');

// Get meta information
echo "Description: " . $beaconData->getMetaField('DESCRIPTION') . "\n";
echo "Creator: " . $beaconData->getMetaField('CREATOR') . "\n";

// Process links
foreach ($beaconData->getConstructedLinks() as $link) {
    echo $link->getSourceIdentifier() . " -> " . $link->getTargetIdentifier() . "\n";

    if ($link->hasAnnotation()) {
        echo "  Annotation: " . $link->getAnnotation() . "\n";
    }
}
```

### Expected Output

[](#expected-output)

```
Description: Example BEACON file mapping people to documents
Creator: Example Organization
http://example.org/people/alice -> http://example.com/documents/alice
http://example.org/people/bob -> http://example.com/documents/bob
  Annotation: author
http://example.org/people/charlie -> http://example.com/documents/special-doc
  Annotation: editor
http://example.org/people/diana -> http://example.net/external-doc

```

### Validation Examples

[](#validation-examples)

```
use BeaconParser\BeaconValidator;

$validator = new BeaconValidator();

// Validate a local file
$result = $validator->validateFile('beacon.txt');

// Validate content from a URL programmatically
$content = file_get_contents('https://example.org/beacon.txt');
$result = $validator->validateString($content);

// Check validation results
if ($result->isValid()) {
    echo "✅ BEACON file is valid\n";
} else {
    echo "❌ BEACON file has errors:\n";
    foreach ($result->getErrors() as $error) {
        echo "  - $error\n";
    }
}

// Show detailed report
echo $result->getDetailedReport();
```

Requirements
------------

[](#requirements)

- PHP 8.0 or higher

Development
-----------

[](#development)

### Running Tests

[](#running-tests)

```
composer test
```

### Code Style

[](#code-style)

```
composer phpcs
```

### Static Analysis

[](#static-analysis)

```
composer phpstan
```

License
-------

[](#license)

MIT License. See [LICENSE](LICENSE) file for details.

Links
-----

[](#links)

- [BEACON Specification](https://gbv.github.io/beaconspec/beacon.html)
- [Wikipedia:BEACON](https://de.wikipedia.org/wiki/Wikipedia:BEACON)

###  Health Score

27

—

LowBetter than 49% of packages

Maintenance58

Moderate activity, may be stable

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity35

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

275d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/76f31e7e6772db47a91388ed82840fae1fa57185bb82a64924bb3839697222c2?d=identicon)[ottosmops](/maintainers/ottosmops)

---

Top Contributors

[![ottosmops](https://avatars.githubusercontent.com/u/4144389?v=4)](https://github.com/ottosmops "ottosmops (8 commits)")

---

Tags

phpparserlibrarybeaconlink-dump

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/ottosmops-beacon/health.svg)

```
[![Health](https://phpackages.com/badges/ottosmops-beacon/health.svg)](https://phpackages.com/packages/ottosmops-beacon)
```

###  Alternatives

[doctrine/lexer

PHP Doctrine Lexer parser library that can be used in Top-Down, Recursive Descent Parsers.

11.2k910.8M118](/packages/doctrine-lexer)[thunderer/shortcode

Advanced shortcode (BBCode) parser and engine for PHP

3892.6M44](/packages/thunderer-shortcode)[simplehtmldom/simplehtmldom

A fast, simple and reliable HTML document parser for PHP.

1921.3M14](/packages/simplehtmldom-simplehtmldom)[corveda/php-sandbox

A PHP library that can be used to run PHP code in a sandboxed environment

23483.5k2](/packages/corveda-php-sandbox)[leonelquinteros/php-toml

PHP parser for TOML language ( https://github.com/toml-lang/toml )

266.7k](/packages/leonelquinteros-php-toml)[sbsaga/toon

🧠 TOON for Laravel — a compact, human-readable, and token-efficient data format for AI prompts & LLM contexts. Perfect for ChatGPT, Gemini, Claude, Mistral, and OpenAI integrations (JSON ⇄ TOON).

6115.6k](/packages/sbsaga-toon)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)