{"id":20739291,"url":"https://github.com/ramy-badr-ahmed/php-swh-client","last_synced_at":"2026-02-17T08:35:30.432Z","repository":{"id":245248954,"uuid":"803845557","full_name":"Ramy-Badr-Ahmed/php-swh-client","owner":"Ramy-Badr-Ahmed","description":"Software Heritage API Client - https://doi.org/10.5281/zenodo.12808864","archived":false,"fork":false,"pushed_at":"2024-11-16T00:52:06.000Z","size":115,"stargazers_count":1,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-24T02:43:08.685Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"https://1959e979-c58a-4d3c-86bb-09ec2dfcec8a.ka.bw-cloud-instance.org/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ramy-Badr-Ahmed.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":"codemeta.json","zenodo":null}},"created_at":"2024-05-21T13:36:11.000Z","updated_at":"2025-04-07T15:57:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"3dc03c03-14da-4702-8c97-e71be711302c","html_url":"https://github.com/Ramy-Badr-Ahmed/php-swh-client","commit_stats":null,"previous_names":["ramy-badr-ahmed/swh-client","ramy-badr-ahmed/php-swh-client"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/Ramy-Badr-Ahmed/php-swh-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ramy-Badr-Ahmed%2Fphp-swh-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ramy-Badr-Ahmed%2Fphp-swh-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ramy-Badr-Ahmed%2Fphp-swh-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ramy-Badr-Ahmed%2Fphp-swh-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ramy-Badr-Ahmed","download_url":"https://codeload.github.com/Ramy-Badr-Ahmed/php-swh-client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ramy-Badr-Ahmed%2Fphp-swh-client/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263091025,"owners_count":23412343,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2024-11-17T06:24:23.028Z","updated_at":"2026-02-17T08:35:25.394Z","avatar_url":"https://github.com/Ramy-Badr-Ahmed.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"![GitHub top language](https://img.shields.io/github/languages/top/Ramy-Badr-Ahmed/swh-client)\n![GitHub](https://img.shields.io/github/license/Ramy-Badr-Ahmed/swh-client)  [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.12808864.svg)](https://doi.org/10.5281/zenodo.12808864)\n\n[![SWH](https://archive.softwareheritage.org/badge/swh:1:dir:ce683dcced024cb3af1db3b01bbe86f2a9b08028/)](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)\n\n# SWH API Client\n\nThis 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.\n\n\u003e[!Note]\n\u003e _**Detailed documentation**_ can be found in the [wiki pages](https://github.com/Ramy-Badr-Ahmed/swh-client/wiki) of this very repository.\n\u003e\n\u003e  A demonstrable version (some features) can be accessed here: \u003ca href=\"https://1959e979-c58a-4d3c-86bb-09ec2dfcec8a.ka.bw-cloud-instance.org/\" target=\"_blank\"\u003e**Demo Version**\u003c/a\u003e\n\u003e\u003e Working on new features and fixes will be gladly considered. Please feel free to report.\n\n## Installation Steps:\n\n    1) Clone this project.\n    \n    2) Open a console session and navigate to the cloned directory:\n    \n        Run \"composer install\"\n\n        This should involve installing the PHP REPL, PsySH\n\n    3) (Optional) Acquire SWH tokens for increased SWH-API Rate-Limits.\n    \n    4) Prepare .env file and add tokens:   \n    \n        4.1) Rename/Copy the cloned \".env.example\" file to .env\n                cp .env.example .env   \n                \n        4.2) (Optional) Edit these two token keys:\n        \n                SWH_TOKEN_PROD=Your_TOKEN_FROM_SWH_ACCOUNT              # step 3)                 \n                SWH_TOKEN_STAGING=Your_STAGING_TOKEN_FROM_SWH_ACCOUNT   # step 3)                 \n\n    5) (optional) Add psysh to PATH.\n\n## Quickstart:\n\nIn a console session inside the cloned directory, start the php REPL:\n\n```php\n$ psysh     // if not added to PATH replace with: vendor/bin/psysh\n\nPsy Shell v0.12.0 (PHP 8.2.0 — cli) by Justin Hileman\n```\n\nThis 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.\n\n### Presets\n\nAs a one-time configuration parameter, you can set the desired returned data type by SWH (default JSON):\n\n```php\n\u003e namespace Module\\HTTPConnector;\n\u003e use Module\\HTTPConnector;         \n\n\u003e HTTPClient::setOptions(responseType:'object')     // json/collect/object available\n```\n\n\u003e * More details on the default configs: [Default Configurations](https://github.com/Ramy-Badr-Ahmed/swh-client/wiki#default-configurations)\n\u003e * More details on further options set: [Preset Configurations](https://github.com/Ramy-Badr-Ahmed/swh-client/wiki).\n\n### Visits\n\nRetrieve Latest Full Visit in the SWH archive:\n\n```php\n\u003e namespace Module\\OriginVisits;\n\u003e use Module\\OriginVisits; \n\n\u003e $visitObject = new SwhVisits('https://github.com/torvalds/linux/');\n\n\u003e $visitObject-\u003egetVisit('latest', requireSnapshot: true)\n```\n\n\u003e More details on further swh visits methods: [SwhVisits](https://github.com/Ramy-Badr-Ahmed/swh-client/wiki#ii-swhvisits).\n\n### DAG Model:\n\nAs graph Nodes, retrieve node Contents, Edges or find a Path to other nodes (top-bottom):\n\n```php\n\u003e namespace Module\\DAGModel;\n\u003e use Module\\DAGModel; \n\n\u003e $snpNode = new GraphNode('swh:1:snp:bcfd516ef0e188d20056c77b8577577ac3ca6e58')\n\n\u003e $snpNode-\u003enodeHopp()   // node contents\n\n\u003e $snpNode-\u003enodeEdges()  // node edges keyed by the respective name\n\n\u003e $revNode = new GraphNode('swh:1:rev:9cf5bf02b583b93aa0d149cac1aa06ee4a4f655c')\n\n\u003e $revNode-\u003enodeTraversal('deps/nghttp2/lib/includes/nghttp2/nghttp2ver.h.in') //  traverse to a deeply nested file\n```\n\nMore details on:\n\n\u003e * General [Node Methods](https://github.com/Ramy-Badr-Ahmed/swh-client/wiki#iii-graphnode).\n\u003e * The Graph methods:\n\u003e   * [Graph contents](https://github.com/Ramy-Badr-Ahmed/swh-client/wiki#iv-graphhopping)\n\u003e   * [Graph edges](https://github.com/Ramy-Badr-Ahmed/swh-client/wiki#v-graphedges)\n\u003e   * [Graph paths](https://github.com/Ramy-Badr-Ahmed/swh-client/wiki#vi-graphtraversal)\n\n### Archive\n\nYou can specify repositories URL w/o paths and archive to SWH using one of the two variants (`static/non-static methods`):\n\n```php\n\u003e namespace Module\\Archival;\n\u003e use Module\\Archival; \n    \n\u003e $saveRequest = new Archive('https://github.com/torvalds/linux/')    // Example 1\n\u003e $saveRequest-\u003esave2Swh()\n    \n\u003e $newSaveRequest = Archive::repository('https://github.com/hylang/hy/tree/stable/hy/core')  // Example 2\n\n    // in both cases: the returned POST response contains the save request id and date\n```\n\nEnquire about archival status using the id/date of the archival request (available in the initial POST response)\n\n```php\n\u003e $saveRequest-\u003egetArchivalStatus($saveRequestDateOrID)     // current status is returned \n\u003e $saveRequest-\u003etrackArchivalStatus($saveRequestDateOrID)   // tracks until archival has succeeded\n```\n\n\u003e More details on further archive methods: [Archive](https://github.com/Ramy-Badr-Ahmed/swh-client/wiki#vii-archive).\n\n### EBNF Grammar\n\nValidate a given swhID. `TypeError` is thrown for non-valid swhIDs.\n\n```php\n\u003e namespace Module\\DataType; \n\u003e use Module\\DataType; \n         \n$snpID = new SwhcoreId('swh:1:snp:bcfd516ef0e188d20056c77b8577577ac3ca6e5Z') // throws TypeError Exception\n```\n\u003e Full details of the SWHID persistent Identifiers: [Syntax](https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html#syntax)\n\n\u003e[!Note]\n\u003e Todo: Core identifiers with qualifiers.\n\n### MetaData\n\nReturns a list of metadata authorities that provided metadata on the given target\n\n```php\n\u003e namespace Module\\MetaData;\n\u003e use Module\\MetaData; \n\n\u003e SwhMetaData::getOriginMetaData('https://github.com/torvalds/linux/')\n```\n\n\u003e More details on further metadata methods: [Metadata](https://github.com/Ramy-Badr-Ahmed/swh-client/wiki#viii-metadata).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framy-badr-ahmed%2Fphp-swh-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Framy-badr-ahmed%2Fphp-swh-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framy-badr-ahmed%2Fphp-swh-client/lists"}