https://github.com/ramy-badr-ahmed/php-swh-client
Software Heritage API Client - https://doi.org/10.5281/zenodo.12808864
https://github.com/ramy-badr-ahmed/php-swh-client
guzzle-clients illuminate-http illuminate-validation merkle-dag php-client psysh software-archiving software-heritage software-heritage-api-client software-heritage-dag swh-api swh-archiver swh-client swh-connector swh-endpoints swh-graph swh-metadata swh-model swh-webclient swhid
Last synced: 6 days ago
JSON representation
Software Heritage API Client - https://doi.org/10.5281/zenodo.12808864
- Host: GitHub
- URL: https://github.com/ramy-badr-ahmed/php-swh-client
- Owner: Ramy-Badr-Ahmed
- License: apache-2.0
- Created: 2024-05-21T13:36:11.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2024-11-16T00:52:06.000Z (5 months ago)
- Last Synced: 2025-04-10T15:18:37.212Z (19 days ago)
- Topics: guzzle-clients, illuminate-http, illuminate-validation, merkle-dag, php-client, psysh, software-archiving, software-heritage, software-heritage-api-client, software-heritage-dag, swh-api, swh-archiver, swh-client, swh-connector, swh-endpoints, swh-graph, swh-metadata, swh-model, swh-webclient, swhid
- Language: PHP
- Homepage: https://1959e979-c58a-4d3c-86bb-09ec2dfcec8a.ka.bw-cloud-instance.org/
- Size: 112 KB
- Stars: 1
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codemeta: codemeta.json
Awesome Lists containing this project
README
 [](https://doi.org/10.5281/zenodo.12808864)
[](https://archive.softwareheritage.org/swh:1:dir:ce683dcced024cb3af1db3b01bbe86f2a9b08028;origin=https://github.com/Ramy-Badr-Ahmed/swh-client;visit=swh:1:snp:63102a06d859d7d3bcccf1bfe5ade84d8e54e2d5;anchor=swh:1:rev:fb18ecd48c6d62947316845716fc578030ccf749)
# SWH API Client
This is a PHP API client/connector for [Software Heritage (SWH) web API](https://archive.softwareheritage.org/api/) - currently in Beta phase. The client is wrapped round the [`Illuminate Http package`](https://packagist.org/packages/illuminate/http) and the [`GuzzleHTTP`](https://docs.guzzlephp.org/en/stable/index.html) library.
>[!Note]
> _**Detailed documentation**_ can be found in the [wiki pages](https://github.com/Ramy-Badr-Ahmed/swh-client/wiki) of this very repository.
>
> A demonstrable version (some features) can be accessed here: **Demo Version**
>> Working on new features and fixes will be gladly considered. Please feel free to report.
## Installation Steps:
1) Clone this project.
2) Open a console session and navigate to the cloned directory:
Run "composer install"
This should involve installing the PHP REPL, PsySH
3) (Optional) Acquire SWH tokens for increased SWH-API Rate-Limits.
4) Prepare .env file and add tokens:
4.1) Rename/Copy the cloned ".env.example" file to .env
cp .env.example .env
4.2) (Optional) Edit these two token keys:
SWH_TOKEN_PROD=Your_TOKEN_FROM_SWH_ACCOUNT # step 3)
SWH_TOKEN_STAGING=Your_STAGING_TOKEN_FROM_SWH_ACCOUNT # step 3)
5) (optional) Add psysh to PATH.
## Quickstart:
In a console session inside the cloned directory, start the php REPL:
```php
$ psysh // if not added to PATH replace with: vendor/bin/psysh
Psy Shell v0.12.0 (PHP 8.2.0 — cli) by Justin Hileman
```
This will open a REPL console-based session where one can test the functionality of the api classes and their methods before building a suitable workflow/use-cases.
### Presets
As a one-time configuration parameter, you can set the desired returned data type by SWH (default JSON):
```php
> namespace Module\HTTPConnector;
> use Module\HTTPConnector;
> HTTPClient::setOptions(responseType:'object') // json/collect/object available
```
> * More details on the default configs: [Default Configurations](https://github.com/Ramy-Badr-Ahmed/swh-client/wiki#default-configurations)
> * More details on further options set: [Preset Configurations](https://github.com/Ramy-Badr-Ahmed/swh-client/wiki).
### Visits
Retrieve Latest Full Visit in the SWH archive:
```php
> namespace Module\OriginVisits;
> use Module\OriginVisits;
> $visitObject = new SwhVisits('https://github.com/torvalds/linux/');
> $visitObject->getVisit('latest', requireSnapshot: true)
```
> More details on further swh visits methods: [SwhVisits](https://github.com/Ramy-Badr-Ahmed/swh-client/wiki#ii-swhvisits).
### DAG Model:
As graph Nodes, retrieve node Contents, Edges or find a Path to other nodes (top-bottom):
```php
> namespace Module\DAGModel;
> use Module\DAGModel;
> $snpNode = new GraphNode('swh:1:snp:bcfd516ef0e188d20056c77b8577577ac3ca6e58')
> $snpNode->nodeHopp() // node contents
> $snpNode->nodeEdges() // node edges keyed by the respective name
> $revNode = new GraphNode('swh:1:rev:9cf5bf02b583b93aa0d149cac1aa06ee4a4f655c')
> $revNode->nodeTraversal('deps/nghttp2/lib/includes/nghttp2/nghttp2ver.h.in') // traverse to a deeply nested file
```
More details on:
> * General [Node Methods](https://github.com/Ramy-Badr-Ahmed/swh-client/wiki#iii-graphnode).
> * The Graph methods:
> * [Graph contents](https://github.com/Ramy-Badr-Ahmed/swh-client/wiki#iv-graphhopping)
> * [Graph edges](https://github.com/Ramy-Badr-Ahmed/swh-client/wiki#v-graphedges)
> * [Graph paths](https://github.com/Ramy-Badr-Ahmed/swh-client/wiki#vi-graphtraversal)
### Archive
You can specify repositories URL w/o paths and archive to SWH using one of the two variants (`static/non-static methods`):
```php
> namespace Module\Archival;
> use Module\Archival;
> $saveRequest = new Archive('https://github.com/torvalds/linux/') // Example 1
> $saveRequest->save2Swh()
> $newSaveRequest = Archive::repository('https://github.com/hylang/hy/tree/stable/hy/core') // Example 2
// in both cases: the returned POST response contains the save request id and date
```
Enquire about archival status using the id/date of the archival request (available in the initial POST response)
```php
> $saveRequest->getArchivalStatus($saveRequestDateOrID) // current status is returned
> $saveRequest->trackArchivalStatus($saveRequestDateOrID) // tracks until archival has succeeded
```
> More details on further archive methods: [Archive](https://github.com/Ramy-Badr-Ahmed/swh-client/wiki#vii-archive).
### EBNF Grammar
Validate a given swhID. `TypeError` is thrown for non-valid swhIDs.
```php
> namespace Module\DataType;
> use Module\DataType;
$snpID = new SwhcoreId('swh:1:snp:bcfd516ef0e188d20056c77b8577577ac3ca6e5Z') // throws TypeError Exception
```
> Full details of the SWHID persistent Identifiers: [Syntax](https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html#syntax)
>[!Note]
> Todo: Core identifiers with qualifiers.
### MetaData
Returns a list of metadata authorities that provided metadata on the given target
```php
> namespace Module\MetaData;
> use Module\MetaData;
> SwhMetaData::getOriginMetaData('https://github.com/torvalds/linux/')
```
> More details on further metadata methods: [Metadata](https://github.com/Ramy-Badr-Ahmed/swh-client/wiki#viii-metadata).