{"id":20244780,"url":"https://github.com/renoki-co/laravel-ec2-metadata","last_synced_at":"2025-04-10T20:50:54.501Z","repository":{"id":36999666,"uuid":"404265901","full_name":"renoki-co/laravel-ec2-metadata","owner":"renoki-co","description":"Retrieve the EC2 Metadata using Laravel's eloquent syntax.","archived":false,"fork":false,"pushed_at":"2024-06-17T17:14:11.000Z","size":64,"stargazers_count":4,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-24T18:21:18.846Z","etag":null,"topics":["aws","ec2","instance","laravel","metadata","php"],"latest_commit_sha":null,"homepage":"","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/renoki-co.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","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":null},"funding":{"github":"rennokki"}},"created_at":"2021-09-08T08:15:13.000Z","updated_at":"2021-12-27T18:01:39.000Z","dependencies_parsed_at":"2024-03-13T17:44:04.501Z","dependency_job_id":null,"html_url":"https://github.com/renoki-co/laravel-ec2-metadata","commit_stats":{"total_commits":48,"total_committers":5,"mean_commits":9.6,"dds":0.5,"last_synced_commit":"d599853e6afc3cd77c20be67ec70c2dc76c970e1"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":"renoki-co/laravel-package-skeleton","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/renoki-co%2Flaravel-ec2-metadata","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/renoki-co%2Flaravel-ec2-metadata/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/renoki-co%2Flaravel-ec2-metadata/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/renoki-co%2Flaravel-ec2-metadata/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/renoki-co","download_url":"https://codeload.github.com/renoki-co/laravel-ec2-metadata/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248296493,"owners_count":21080301,"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":["aws","ec2","instance","laravel","metadata","php"],"created_at":"2024-11-14T09:17:22.155Z","updated_at":"2025-04-10T20:50:54.481Z","avatar_url":"https://github.com/renoki-co.png","language":"PHP","funding_links":["https://github.com/sponsors/rennokki"],"categories":[],"sub_categories":[],"readme":"Laravel EC2 Metadata\n====================\n\n![CI](https://github.com/renoki-co/laravel-ec2-metadata/workflows/CI/badge.svg?branch=master)\n[![codecov](https://codecov.io/gh/renoki-co/laravel-ec2-metadata/branch/master/graph/badge.svg)](https://codecov.io/gh/renoki-co/laravel-ec2-metadata/branch/master)\n[![StyleCI](https://github.styleci.io/repos/404265901/shield?branch=master)](https://github.styleci.io/repos/404265901)\n[![Latest Stable Version](https://poser.pugx.org/renoki-co/laravel-ec2-metadata/v/stable)](https://packagist.org/packages/renoki-co/laravel-ec2-metadata)\n[![Total Downloads](https://poser.pugx.org/renoki-co/laravel-ec2-metadata/downloads)](https://packagist.org/packages/renoki-co/laravel-ec2-metadata)\n[![Monthly Downloads](https://poser.pugx.org/renoki-co/laravel-ec2-metadata/d/monthly)](https://packagist.org/packages/renoki-co/laravel-ec2-metadata)\n[![License](https://poser.pugx.org/renoki-co/laravel-ec2-metadata/license)](https://packagist.org/packages/renoki-co/laravel-ec2-metadata)\n\nRetrieve the EC2 Metadata using Laravel's eloquent syntax.\n\n## 🤝 Supporting\n\n**If you are using one or more Renoki Co. open-source packages in your production apps, in presentation demos, hobby projects, school projects or so, sponsor our work with [Github Sponsors](https://github.com/sponsors/rennokki). 📦**\n\n[\u003cimg src=\"https://github-content.s3.fr-par.scw.cloud/static/20.jpg\" height=\"210\" width=\"418\" /\u003e](https://github-content.renoki.org/github-repo/20)\n\n## 🚀 Installation\n\nYou can install the package via composer:\n\n```bash\ncomposer require renoki-co/laravel-ec2-metadata\n```\n\n## 🙌 Usage\n\nThe package was made to be easier for you to implement your own methods and keep it simple, without hassling too much about requests.\n\nIn this brief example, you can calculate the seconds left until the EC2 Spot instance will be terminated.\n\n```php\nuse Carbon\\Carbon;\nuse RenokiCo\\Ec2Metadata\\Ec2Metadata;\n\nif ($termination = Ec2Metadata::terminationNotice()) {\n    // The instance is terminating...\n\n    $secondsRemaining = Carbon::parse($termination['time'])-\u003ediffInSeconds(now());\n\n    echo \"The instance is terminating in {$secondsRemaining} seconds.\";\n}\n```\n\n## Setting Version\n\nThe default version of the Ec2Metadata class is `latest`, but to avoid your code to break due to API changes, define the version to run on.\n\nYou can see the list of available versions [in IMDSv2 documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-retrieval.html), under `Get the available versions of the instance metadata`:\n\n```php\nuse RenokiCo\\Ec2Metadata\\Ec2Metadata;\n\nEc2Metadata::version('2016-09-02');\n```\n\n## Calling Custom Endpoints\n\nThe IMDSv2 API is pretty complex, and there are some functions you can use from the `Ec2Metadata` class, just for convenience. When you want to retrieve data from an endpoint that's not implemented, you can either define a macro or use the `get()` and `getJson()` functions to retrieve in plain-text or as a JSON-decoded array:\n\nTake this example for retrieving the kernel ID (under `/meta-data/kernel-id`):\n\n```php\nuse RenokiCo\\Ec2Metadata\\Ec2Metadata;\n\n$kernelId = Ec2Metadata::get('kernel-id');\n```\n\nTo retrieve JSON values, you may call `getJson`. This will work properly only if the expected value from the endpoint you call will be a JSON-encoded response.\n\nIn the implementation, `terminationNotice` uses the `getJson()` to retrieve the response:\n\n```php\nclass Ec2Metadata\n{\n    public static function terminationNotice(): array\n    {\n        // Expected response is {\"action\": \"terminate\", \"time\": \"2017-09-18T08:22:00Z\"}\n        return static::getJson('/spot/instance-action');\n    }\n}\n```\n\n## Macros\n\nAlternatively to using `get()` and `getJson()`, you can define macros:\n\n```php\nuse RenokiCo\\Ec2Metadata\\Ec2Metadata;\n\nEc2Metadata::macro('kernelId', function () {\n    return static::get('kernel-id');\n});\n\n$kernelId = Ec2Metadata::kernelId();\n```\n\n## Testing Your Code\n\nThe package is using [HTTP Client](https://laravel.com/docs/8.x/http-client), a Laravel feature that leverages Guzzle and you can handle requests and test them by [mocking responses](https://laravel.com/docs/8.x/http-client#testing).\n\nTesting properly your app means you should be fully trained with the [AWS EC2's IMDSv2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html) API, in order to provider appropriate responses.\n\nWhen pushing the responses in testing, make sure to take into account that the first call would be the token retrieval.\n\n```php\nuse Illuminate\\Http\\Client\\Request;\nuse Illuminate\\Support\\Facades\\Http;\nuse RenokiCo\\Ec2Metadata\\Ec2Metadata;\n\nHttp::fake([\n    'http://169.254.169.254/*' =\u003e Http::sequence()\n        -\u003epush('some-token', 200)\n        -\u003epush('ami-1234', 200),\n]);\n\n$this-\u003eassertEquals('ami-1234', Ec2Metadata::ami());\n\nHttp::assertSentInOrder([\n    function (Request $request) {\n        return $request-\u003emethod() === 'PUT' \u0026\u0026\n            $request-\u003eurl() === 'http://169.254.169.254/latest/api/token' \u0026\u0026\n            $request-\u003eheader('X-AWS-EC2-Metadata-Token-TTL-Seconds') === ['21600'];\n    },\n    function (Request $request) {\n        return $request-\u003emethod() === 'GET' \u0026\u0026\n            $request-\u003eurl() === 'http://169.254.169.254/latest/meta-data/ami-id' \u0026\u0026\n            $request-\u003eheader('X-AWS-EC2-Metadata-Token') === ['some-token'];\n    },\n]);\n```\n\n## 🐛 Testing\n\n``` bash\nvendor/bin/phpunit\n```\n\n## 🤝 Contributing\n\nPlease see [CONTRIBUTING](CONTRIBUTING.md) for details.\n\n## 🔒  Security\n\nIf you discover any security related issues, please email alex@renoki.org instead of using the issue tracker.\n\n## 🎉 Credits\n\n- [Alex Renoki](https://github.com/rennokki)\n- [All Contributors](../../contributors)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frenoki-co%2Flaravel-ec2-metadata","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frenoki-co%2Flaravel-ec2-metadata","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frenoki-co%2Flaravel-ec2-metadata/lists"}