PHPackages                             ophelios/php-lighthouse-storage - 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. [File & Storage](/categories/file-storage)
4. /
5. ophelios/php-lighthouse-storage

ActiveLibrary[File & Storage](/categories/file-storage)

ophelios/php-lighthouse-storage
===============================

Simple library for storing data in a Lighthouse (Web3 Storage, IPFS, Filecoin).

030PHPCI passing

Since Oct 23Pushed 8mo agoCompare

[ Source](https://github.com/ophelios-studio/php-lighthouse-storage)[ Packagist](https://packagist.org/packages/ophelios/php-lighthouse-storage)[ RSS](/packages/ophelios-php-lighthouse-storage/feed)WikiDiscussions main Synced 3w ago

READMEChangelogDependenciesVersions (1)Used By (0)

PHP Lighthouse Storage
======================

[](#php-lighthouse-storage)

[![Maintainability](https://camo.githubusercontent.com/626c4582bff7e3972edb07bd43171acf9bbd7c6237def9d136cd8de1f6732b00/68747470733a2f2f716c74792e73682f6261646765732f30363133393565632d323436652d346266302d623365382d3331323865356566656332372f6d61696e7461696e6162696c6974792e737667)](https://qlty.sh/gh/ophelios-studio/projects/php-lighthouse-storage)[![Code Coverage](https://camo.githubusercontent.com/25e84aaa881b342c20103e8abece287e68e12e5d087bec8112fbf94218828106/68747470733a2f2f716c74792e73682f6261646765732f30363133393565632d323436652d346266302d623365382d3331323865356566656332372f636f7665726167652e737667)](https://qlty.sh/gh/ophelios-studio/projects/php-lighthouse-storage)

A tiny PHP library to upload files and fetch file information from Lighthouse (Web3 storage on IPFS/Filecoin). Simple facade over Guzzle and a typed result object.

✨ Features
----------

[](#-features)

- Upload a file to Lighthouse and get back its CID (hash)
- Fetch file information by CID
- Build a public gateway URL for a CID
- Typed result: Lighthouse\\LighthouseFile with common fields
- Guzzle-based HTTP client with unified LighthouseException errors

💿 Installation
--------------

[](#-installation)

Install with Composer:

```
composer require ophelios/php-lighthouse-storage

```

Requirements: PHP >= 8.4

🌱 Quick start
-------------

[](#-quick-start)

```
use Lighthouse\LighthouseService;

$apiKey  = getenv('LIGHTHOUSE_API_KEY');
$service = new LighthouseService($apiKey);

// Get file information by CID
$cid  = 'bafkreih2ayd35c7a4xc2zqh5uma7uxkgfqs7uzarnwe5q7nul34ibmrchi';
$file = $service->getFileInfo($cid);

if ($file) {
    echo $file->fileName . " (" . $file->mimeType . ") => " . $file->fileSizeInBytes . " bytes\n";
    echo "Gateway URL: " . $file->getUrl() . "\n"; // convenience shortcut
}

// Upload a local file and get its CID
$cid = $service->uploadFile(__DIR__ . '/path/to/local-file.png');
echo "Uploaded CID: $cid\n";

// Build a public URL from a CID (static helper)
echo LighthouseService::getFileUrl($cid) . "\n";
```

📦 Result type: LighthouseFile
-----------------------------

[](#-result-type-lighthousefile)

The library maps Lighthouse API JSON into a typed object with readonly properties:

- fileSizeInBytes (int)
- cid (string)
- encryption (bool)
- fileName (string)
- mimeType (string)
- txHash (string)

Helpers:

- getUrl(): returns the default gateway URL for this CID

Factory:

- LighthouseFile::buildFromResponse(string|array|null): ?LighthouseFile

⚙️ Custom client/configuration
------------------------------

[](#️-custom-clientconfiguration)

If you need to control timeouts or inject your own client, you can pass a LighthouseClient built with a Configuration. The client wraps Guzzle and is already configured with your API key and JSON headers.

```
use Lighthouse\Configuration;
use Lighthouse\LighthouseClient;
use Lighthouse\LighthouseService;

$cfg = new Configuration(
    apiKey: getenv('LIGHTHOUSE_API_KEY'),
    timeout: 30.0,
);
$client  = new LighthouseClient($cfg);
$service = new LighthouseService($client);
```

🧪 Testing
---------

[](#-testing)

This repository includes unit tests and an optional live integration test.

Run all tests:

```
vendor/bin/phpunit

```

Run unit tests only:

```
vendor/bin/phpunit --testsuite Unit

```

Integration test requires a Lighthouse API key. You can place it in an .env file at the project root:

```
LIGHTHOUSE_API_KEY=your-key-here

```

Then run:

```
vendor/bin/phpunit --testsuite Integration

```

Tip: To generate coverage locally, enable Xdebug or pcov (CI already runs with coverage enabled).

🚨 Errors
--------

[](#-errors)

All errors thrown by this library, including those originating from Guzzle, are wrapped in Lighthouse\\LighthouseException. Catch this exception to handle failures uniformly.

🤝 Contributing
--------------

[](#-contributing)

- Open an issue for bugs or feature ideas
- Submit a PR with a clear description and tests when applicable

📄 License
---------

[](#-license)

MIT License © 2025 Ophelios. See LICENSE for details.

###  Health Score

18

—

LowBetter than 8% of packages

Maintenance43

Moderate activity, may be stable

Popularity9

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity13

Early-stage or recently created project

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.

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/118052280?v=4)[ophelios](/maintainers/ophelios)[@Ophelios](https://github.com/Ophelios)

### Embed Badge

![Health badge](/badges/ophelios-php-lighthouse-storage/health.svg)

```
[![Health](https://phpackages.com/badges/ophelios-php-lighthouse-storage/health.svg)](https://phpackages.com/packages/ophelios-php-lighthouse-storage)
```

###  Alternatives

[venveo/craft-compress

Create smart zip files from Craft assets on the fly

124.7k](/packages/venveo-craft-compress)

PHPackages © 2026

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