{"id":19826247,"url":"https://github.com/aternosorg/php-curseforge-api","last_synced_at":"2025-10-10T09:36:51.612Z","repository":{"id":157409629,"uuid":"633474040","full_name":"aternosorg/php-curseforge-api","owner":"aternosorg","description":"PHP Client for the CurseForge API.","archived":false,"fork":false,"pushed_at":"2025-04-10T14:28:20.000Z","size":408,"stargazers_count":4,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-30T21:46:42.048Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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-04-27T15:17:07.000Z","updated_at":"2025-04-10T14:17:17.000Z","dependencies_parsed_at":"2023-12-14T16:51:32.422Z","dependency_job_id":"4efc78b7-e338-4e96-9bb9-70fb30a09fe9","html_url":"https://github.com/aternosorg/php-curseforge-api","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aternosorg%2Fphp-curseforge-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aternosorg%2Fphp-curseforge-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aternosorg%2Fphp-curseforge-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aternosorg%2Fphp-curseforge-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aternosorg","download_url":"https://codeload.github.com/aternosorg/php-curseforge-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251889967,"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:52.131Z","updated_at":"2025-10-10T09:36:46.584Z","avatar_url":"https://github.com/aternosorg.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Aternos/php-curseforge-api\nAn API client for the CurseForge API written in PHP. This client is a combination of code\ngenerated by OpenAPI Generator using our [openapi spec](./openapi.yaml) and some wrappers\naround it to improve the usability.\n\nThe generated code can be found in `lib/Api` and `lib/Model`. It is recommended to use the\nwrappers in `lib/Client` instead of the generated code.\n\n## Installation\nInstall the package via composer:\n```bash\ncomposer require aternos/curseforge-api\n```\n\n## Usage\n\nThe main entry point for the API is the `CurseForgeAPIClient` class.\n```php\n\u003c?php\nuse Aternos\\CurseForgeApi\\Client\\CurseForgeAPIClient;\n$client = new CurseForgeAPIClient(\"api-key\");\n\n// set a user agent (recommended)\n$client-\u003esetUserAgent('aternos/php-curseforge-api-example');\n```\n**You need an API key to use this client.** If you're a third party you can read more\nabout how to get one [here](https://support.curseforge.com/en/support/solutions/articles/9000208346).\n\n## Paginated Lists\nMost methods return a paginated list containing 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 that returns the underlying array of results.\n\n## Games\nThe `getGames` method for example returns a paginated list of games.\n```php\n$games = $client-\u003egetGames();\n\nforeach ($games as $game) {\n    // like most other methods, this method returns a wrapper\n    // you can use the getData() method to get the game data\n    echo $game-\u003egetData()-\u003egetName() . PHP_EOL;\n}\n\n$games = $games-\u003egetNextPage();\n\nforeach ($games as $game) {\n    echo $game-\u003egetData()-\u003egetName() . PHP_EOL;\n}\n```\nYou can also call `getGame` with the ID of a game to get a specific game. For example, 432 is the ID for Minecraft.\n```php\n$game = $client-\u003egetGame(432);\necho $game-\u003egetData()-\u003egetSlug() . PHP_EOL;\n```\n\n### Game Versions\nA game contains various different version types, you can fetch them like this:\n```php\n$versionTypes = $client-\u003egetGameVersionTypes(432);\n// or\n$versionTypes = $game-\u003egetVersionTypes();\n```\nSince this endpoint isn't paginated, it returns an array instead of a paginated list.\n\nYou can also fetch the versions of a specific version type:\n```php\n$versions = $client-\u003egetGameVersionTypeVersions(432, 68441);\n// or\n$versionType = $versionTypes[0];\n$versions = $versionType-\u003egetVersions();\n```\nFor example: 68441 is the mod loader selection for Minecraft.\n\nYou can also get all versions for all version types of a game:\n```php\n$versions = $client-\u003egetGameVersions(432);\n// or\n$versions = $game-\u003egetVersions();\n```\n\n### Game Categories\nA Game on CurseForge has category classes and categories.\nCategory classes are like \"Modpacks\" or \"Plugins\" and categories are like \"World Generation\" or \"Chat\".\nYou can fetch them like this:\n```php\n$categoryClasses = $client-\u003egetCategories(432);\n// or\n$categoryClasses = $game-\u003egetCategories();\n```\nNote that this will return both, category classes AND categories.\n\nIf you want to get only the category classes you can set the parameter `onlyClasses` to `true`:\n```php\n$categoryClasses = $client-\u003egetCategories(432, null, true);\n// or\n$categoryClasses = $game-\u003egetCategories(null, true);\n```\n\nYou can fetch categories in a class using the parameter `classId`:\n```php\n$categories = $client-\u003egetCategories(432, 6);\n// or\n$categories = $game-\u003egetCategories(6);\n```\n\n## Mods\nYou can search mods like this:\n```php\n$options = new ModSearchOptions(432); // the game ID is required\n$mods = $this-\u003eapiClient-\u003esearchMods($options);\n// or\n$mods = $game-\u003esearchMods(); // options are optional here\n```\n\nYou can also get a list of featured mods for a game:\n```php\n$mods = $client-\u003egetFeaturedMods(432);\n// or\n$mods = $game-\u003egetFeaturedMods();\n\n$featured = $mods-\u003egetFeatured();\n$popular = $mods-\u003egetPopular();\n$recentlyUpdated = $mods-\u003egetRecentlyUpdated();\n```\n\nYou can fetch an individual mod by its ID like this:\n```php\n$mod = $client-\u003egetMod(420561);\n```\nor multiple mods in bulk\n```php\n$mods = $client-\u003egetMods([420561, 278568, 715033]);\n```\n\nYou can also fetch the HTML for mod descriptions:\n```php\n$description = $mod-\u003egetDescription();\n```\n\n### Mod Files\nTo fetch mod files use the method `getFiles()`:\n```php\n$files = $mod-\u003egetFiles();\n```\nIt optionally takes a ModFilesOptions object as a parameter:\n```php\n$options = new ModFilesOptions($mod-\u003egetData()-\u003egetId());\n$options-\u003esetGameVersion(\"1.19.2\");\n\nuse \\Aternos\\CurseForgeApi\\Client\\Options\\ModSearch\\ModLoaderType;\n$options-\u003esetModLoaderType(ModLoaderType::FORGE);\n```\n\nThere also is a method for this in the client, so you don't have to fetch the mod first:\n```php\n$options = new ModFilesOptions(420561);\n$options-\u003esetGameVersion(\"1.19.2\");\n$options-\u003esetModLoaderType(ModLoaderType::FORGE);\n$files = $client-\u003egetModFiles($options);\n```\nIn this case the options are not optional as the mod id is required.\n\nJust like with mods, you can fetch files individually or in bulk:\n```php\n$file = $client-\u003egetModFile(420561, 3787455);\n// or\n$files = $client-\u003egetModFiles([3787455, 3787456]);\n```\nNote that the bulk endpoint doesn't require a mod id.\n\n#### File Download URLs\nYou can get the download URL for a file like this:\n```php\n$url = $file-\u003egetData()-\u003egetDownloadUrl();\n// or if you don't already have the file object\n$url = $client-\u003egetModFileDownloadUrl(420561, 3787455);\n```\nHowever, this will be null (in the first example) or a 403 error (in the second example)\nif the mod does not allow [project distribution](https://support.curseforge.com/en/support/solutions/articles/9000207877).\n\n## Fingerprints\nYou can search files on CurseForge by their fingerprint.\nFor example, this can be used to find the download source for a mod that is installed on a server.\nCurseForge uses a variant of Murmur2 hashing with seed 1 for these fingerprints.\n\n### Obtaining fingerprints\nFrom the API:\n```php\n$file = $client-\u003egetModFile(420561, 3787455);\n$fingerprint = $file-\u003egetFileFingerprint();\n```\n\nFrom a raw string using our CursedFingerprintHelper class:\n```php\n$fingerprint = CursedFingerprintHelper::getFingerprint(\"foo\");\n```\n\nFrom a local file using our helper class:\n```php\n$fingerprint = CursedFingerprintHelper::getFingerprintFromFile(\"/path/to/file.jar\");\n```\nThis will read the file in chunks and calculate the fingerprint from that.\n\nFrom any source using our helper class:\n```php\n$helper = new CursedFingerprintHelper($length);\n\nwhile ($source-\u003ehasNextChunk()) {\n    $helper-\u003enextChunk($source-\u003egetNextChunk());\n}\n\n$fingerprint = $helper-\u003efinalize();\n```\nNote that the length field has to exclude whitespaces (\\x09, \\x0a, \\x0d, \\x20).\nYou can use the `stripWhiteSpcaes` or `isWhiteSpaceCharacter` methods to do that.\n\n### Obtaining matches\n```php\n$files = $client-\u003egetFilesByFingerPrintMatches([1949504940, 1177254054]);\nforeach ($files as $file) {\n    echo $file-\u003egetFile()-\u003egetDisplayName() . PHP_EOL;\n}\n```\n\n## Minecraft\nThere are a few Minecraft specific API endpoints as well:\n\n```php\n// Get Minecraft versions\n$versions = $client-\u003egetMinecraftVersions();\n\n// Get a specific version\n$version = $client-\u003egetMinecraftVersion(\"1.19.2\");\n\n// Get mod loader versions\n$modLoaders = $client-\u003egetMinecraftModLoaders();\n$modLoaders = $client-\u003egetMinecraftModLoaders(\"1.19.2\"); // optionally provide a Minecraft version\n$modLoaders = $client-\u003egetMinecraftModLoaders(null, true); // show all loaders, including fabric\n\n// get more information about a mod loader version\n$version = $client-\u003egetMinecraftModLoader(\"forge-43.2.8\");\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```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faternosorg%2Fphp-curseforge-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faternosorg%2Fphp-curseforge-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faternosorg%2Fphp-curseforge-api/lists"}