{"id":19826236,"url":"https://github.com/aternosorg/php-modrinth-api","last_synced_at":"2025-05-01T14:31:01.842Z","repository":{"id":176634719,"uuid":"659233354","full_name":"aternosorg/php-modrinth-api","owner":"aternosorg","description":"PHP Client for the Modrinth API. This client is based on the openapi spec.","archived":false,"fork":false,"pushed_at":"2025-01-20T16:25:59.000Z","size":835,"stargazers_count":0,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-30T21:46:42.301Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://packagist.org/packages/aternos/modrinth-api","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aternosorg.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}},"created_at":"2023-06-27T11:59:36.000Z","updated_at":"2025-01-21T15:28:31.000Z","dependencies_parsed_at":"2024-01-09T11:52:40.068Z","dependency_job_id":null,"html_url":"https://github.com/aternosorg/php-modrinth-api","commit_stats":null,"previous_names":["aternosorg/php-modrinth-api"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aternosorg%2Fphp-modrinth-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aternosorg%2Fphp-modrinth-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aternosorg%2Fphp-modrinth-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aternosorg%2Fphp-modrinth-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aternosorg","download_url":"https://codeload.github.com/aternosorg/php-modrinth-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251889962,"owners_count":21660422,"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":[],"created_at":"2024-11-12T11:09:50.213Z","updated_at":"2025-05-01T14:31:01.358Z","avatar_url":"https://github.com/aternosorg.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Aternos/php-modrinth-api\nAn API client for the Modrinth API written in PHP. This client is a combination of\ncode generated by OpenAPI Generator and some wrappers around it to improve the\nusability.\n\nThe generated code can be found in `lib/Api` and `lib/Model`. It is recommended\nto use the Wrappers in `lib/Client` instead of the generated code.\n\n## Installation\nInstall the package via composer:\n```bash\ncomposer require aternos/modrinth-api\n```\n\n## Usage\n\nThe main entry point for the API is the `ModrinthAPIClient` class.\n```php\n\u003c?php\nuse Aternos\\ModrinthApi\\Client\\ModrinthAPIClient;\n\n// create an API client. This is the main entry point for the API\n$modrinthClient = new ModrinthAPIClient();\n\n// set a user agent (recommended)\n$modrinthClient-\u003esetUserAgent('aternos/php-modrinth-api-example');\n\n// set an api token (optional)\n$modrinthClient-\u003esetApiToken(\"api-token\");\n```\nThe API Token is only required for non-public requests but if it is provided, it will be used for all requests.\n\n## Paginated Lists\nSome methods return a paginated list which contains a list of results on the current page and methods to\nnavigate to the next and previous page. The paginated list implements `Iterator`, `ArrayAccess` and `Countable` so\nyou can use it like an array. It also has a `getResults()` method which returns the underlying array of results.\n\n### Searching for Projects\n```php\n$projects = $modrinthClient-\u003esearchProjects();\n\nforeach ($project as $project) {\n    // like most other methods, this method returns a wrapper\n    // you can use the getData() method to get the project data\n    echo $project-\u003egetData()-\u003egetTitle() . PHP_EOL;\n}\n\n$projects = $projects-\u003egetNextPage();\n\nforeach ($projects as $project) {\n    echo $project-\u003egetData()-\u003egetTitle() . PHP_EOL;\n}\n```\n\n### Search for Projects with Options\nYou can apply filters and change the sort order when searching for projects.\nAll options are optional and can be combined.\n```php\nuse \\Aternos\\ModrinthApi\\Client\\Options\\ProjectSearchOptions;\nuse \\Aternos\\ModrinthApi\\Client\\Options\\SearchIndex;\n\n$options = new ProjectSearchOptions();\n$options-\u003esetQuery(\"mclogs\");\n$options-\u003esetSearchIndex(SearchIndex::UPDATED);\n$projects = $modrinthClient-\u003egetProjects($options);\n```\n\n#### Facets\nOne way to filter search results are facets. Facets specify which loader, category, game version or license to filter for.\nYou need to provide exactly one AND group which can consist of multiple OR groups: \n```php\nuse \\Aternos\\ModrinthApi\\Client\\Options\\Facets\\Facet;\nuse \\Aternos\\ModrinthApi\\Client\\Options\\Facets\\FacetType;\nuse \\Aternos\\ModrinthApi\\Client\\Options\\Facets\\FacetORGroup;\nuse \\Aternos\\ModrinthApi\\Client\\Options\\Facets\\FacetANDGroup;\n\n$facetOrGroup = new FacetORGroup();\n$facetOrGroup-\u003eaddFacet(new Facet(FacetType::VERSIONS, \"1.20.1\"))\n             -\u003eaddFacet(new Facet(FacetType::VERSIONS, \"1.20\"));\n\n// or add multiple facets at once:\n$facetOrGroup-\u003eaddFacets(\n    new Facet(FacetType::VERSIONS, \"1.19.4\"),\n    new Facet(FacetType::VERSIONS, \"1.19.3\")\n);\n\n// alternatively if all facets have the same type:\n$facetOrGroup-\u003eaddFacets(FacetType::VERSIONS, \"1.19.2\", \"1.19.1\", \"1.19\");\n\n$options-\u003esetFacets($facetOrGroup);\n\n// if you want to combine multiple OR groups, you can use an AND group:\n$facetAndGroup = new FacetANDGroup();\n$facetAndGroup-\u003eaddORGroup($facetOrGroup)\n              -\u003eaddORGroup(new FacetORGroup(new Facet(FacetType::LICENSE, \"MIT\")));\n              \n// or\n$facetAndGroup = $facetOrGroup-\u003etoANDGroup()\n    -\u003eaddORGroup(new FacetORGroup(new Facet(FacetType::LICENSE, \"MIT\")));\n\n$options-\u003esetFacets($facetAndGroup);\n\n$projects = $modrinthClient-\u003egetProjects($options);\n```\n\nBy default facets are checked using the equals operator. There are several other operators available:\n```php\nuse \\Aternos\\ModrinthApi\\Client\\Options\\Facets\\FacetOperator;\n\n$facet = new Facet(FacetType::DOWNLOADS, \"1.20.1\", FacetOperator::GREATER_THAN);\n```\n\n## Getting Additional Project Data\nThe Project wrapper provides methods to fetch additional data about the project.\n```php\n// get a specific project\n$project = $modrinthClient-\u003egetProject(\"mclogs\");\n\n// get versions of the project\n$versions = $project-\u003egetVersions();\n\n// get a specific version\n$version = $project-\u003egetVersion(\"2.6.2\");\n\n// get the members of the project\n$members = $project-\u003egetMembers();\n```\n\n## Fetching Projects\nYou can also fetch individual projects by their id or slug:\n```php\n$project = $modrinthClient-\u003egetProject(\"mclogs\");\n```\n\nor multiple projects by their ids:\n```php\n$projects = $modrinthClient-\u003egetProjects([\"6DdCzpTL\", \"VPo0otUH\"]);\n```\nIt seems like fetching by slugs is also supported here but this is not documented.\n\n### Check if a slug/id is used\n```php\n$projectId = $modrinthClient-\u003echeckProjectValidity(\"mclogs\");\n\nif ($projectId) {\n    echo \"project exists, id:\" . $projectId;\n} else {\n    echo \"project does not exist\";\n}\n```\n\n### Project Dependencies\nGet dependencies of a project\n```php\n$dependencies = $project-\u003egetDependencies();\n\n// on modrinth you can depend on a project or directly on a version\n$projects = $dependencies-\u003egetProjects();\n$versions = $dependencies-\u003egetVersions();\n```\n\n\n## Versions\n```php\n// get versions of a project by name\n$versions = $modrinthClient-\u003egetProjectVersions(\"mclogs\");\n\n// get the versions from a project\n$versions = $project-\u003egetVersions();\n\n// get a specific version by its id\n$version = $modrinthClient-\u003egetVersion(\"xzRGr4AC\");\n\n// get multiple versions by their ids\n$versions = $modrinthClient-\u003egetVersions([\"xzRGr4AC\", \"EwNN8uNA\"]);\n```\n\n## Hashes\nThe modrinth API also allows you to find a version by its SHA1 or SHA512 hash:\n```php\nuse \\Aternos\\ModrinthApi\\Client\\HashAlgorithm;\n\n$hash = \"5952253d61e199e82eb852c5824c3981b29b209d\";\n\n// returns the modrinth version for the given hash\n$version = $modrinthClient-\u003egetVersionByHash($hash, HashAlgorithm::SHA1);\n\n// fetch multiple versions at once\n$versions = $modrinthClient-\u003egetVersionsByHashes([$hash], HashAlgorithm::SHA1);\n\n// returns the latest version for a specific loader and version\n$version = $modrinthClient-\u003egetLatestVersionByHash($hash, [\"spigot\"], [\"1.19.4\"], HashAlgorithm::SHA1);\n\n// fetch multiple versions at once\n$versions = $modrinthClient-\u003egetLatestVersionsByHashes([$hash], [\"spigot\"], [\"1.19.4\"], HashAlgorithm::SHA1);\n```\n\n## Users\n```php\n// get a user\n$user = $modrinthClient-\u003egetUser(\"matthias\");\n\n// get projects of a user\n$projects = $user-\u003egetProjects();\n\n// get notifications (requires authentication)\n$notifications = $user-\u003egetNotifications();\n\n// get followed projects (requires authentication)\n$projects = $user-\u003egetFollowedProjects();\n\n// get payout history (requires authentication)\n$history = $user-\u003egetPayoutHistory();\n```\n\n## Teams\n```php\n// get the members of a team\n$members = $modrinthClient-\u003egetTeamMembers(\"ThaUQrOs\");\n\n// get the members of multiple teams at once\n$teams = $modrinthClient-\u003egetTeams([\"ThaUQrOs\"]);\n```\n\n## Tags\nYou can fetch all available categories, loaders, game versions and licenses from the API.\nOur library provides methods to search projects by these directly:\n```php\n$categories = $modrinthClient-\u003egetCategories();\n$categories[0]-\u003esearchProjects();\n$loaders = $modrinthClient-\u003egetLoaders();\n$loaders[0]-\u003esearchProjects();\n$gameVersions = $modrinthClient-\u003egetGameVersions();\n$gameVersions[0]-\u003esearchProjects();\n$licenses = $modrinthClient-\u003egetLicenses();\n$licenses[0]-\u003esearchProjects();\n```\n\nYou can also fetch donation platforms and report types:\n```php\n$reportTypes = $modrinthClient-\u003egetReportTypes();\n$donationPlatforms = $modrinthClient-\u003egetDonationPlatforms();\n```\n\n\n## Updating the generated code\nThe generated code can be updated by installing the [openapi generator](https://openapi-generator.tech/docs/installation) running the following command:\n```bash\nopenapi-generator-cli generate -c config.yaml\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faternosorg%2Fphp-modrinth-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faternosorg%2Fphp-modrinth-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faternosorg%2Fphp-modrinth-api/lists"}