{"id":15019825,"url":"https://github.com/butschster/lumenmicroservice","last_synced_at":"2025-10-24T18:30:22.093Z","repository":{"id":55574411,"uuid":"305186074","full_name":"butschster/LumenMicroservice","owner":"butschster","description":"This Package helps you to use Lumen framework as a microservice with AMQP and JMS Serializer without extra knowledge.","archived":false,"fork":false,"pushed_at":"2021-01-21T13:06:48.000Z","size":140,"stargazers_count":5,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-31T03:32:11.199Z","etag":null,"topics":["amqp","jms-serializer","laravel","laravel8","lumen","lumen-framework","microservice","mq","php","rabbitmq"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/butschster.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-10-18T20:03:33.000Z","updated_at":"2024-07-08T16:13:03.000Z","dependencies_parsed_at":"2022-08-15T03:30:32.929Z","dependency_job_id":null,"html_url":"https://github.com/butschster/LumenMicroservice","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/butschster%2FLumenMicroservice","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/butschster%2FLumenMicroservice/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/butschster%2FLumenMicroservice/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/butschster%2FLumenMicroservice/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/butschster","download_url":"https://codeload.github.com/butschster/LumenMicroservice/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238016118,"owners_count":19402506,"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":["amqp","jms-serializer","laravel","laravel8","lumen","lumen-framework","microservice","mq","php","rabbitmq"],"created_at":"2024-09-24T19:54:09.754Z","updated_at":"2025-10-24T18:30:16.658Z","avatar_url":"https://github.com/butschster.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lumen Microservice\n[![Build Status](https://travis-ci.org/butschster/LumenMicroservice.svg)](https://travis-ci.org/butschster/LumenMicroservice) [![Latest Stable Version](https://poser.pugx.org/butschster/lumen-microservice/v/stable)](https://packagist.org/packages/butschster/lumen-microservice) [![Total Downloads](https://poser.pugx.org/butschster/lumen-microservice/downloads)](https://packagist.org/packages/butschster/lumen-microservice) [![License](https://poser.pugx.org/butschster/lumen-microservice/license)](https://packagist.org/packages/butschster/lumen-microservice)\n![heading](https://user-images.githubusercontent.com/773481/96422465-b6bbe800-1200-11eb-914a-8c2c150d80eb.jpg)\n\nThis Package can help you to use Lumen framework or Laravel as a microservice without extra knowledge. \nJust install package, create Exchange Point class and start exchanging information between services through MQ.\n\nThis package uses [JMS\\Serializer](https://github.com/schmittjoh/serializer) for message serialization.\n\n*P.S. You can use this service for testing https://www.cloudamqp.com. They have a free plan.*\n\n## Features\n- Easy to use out of the box\n- Easy to configure\n- jms serializer\n- Uses MQ out of the box\n- Well tested\n\n## Requirements\n- Lumen or Laravel 7.x to 8.x\n- PHP 7.4 and above\n   \n## Installation and Configuration\nFrom the command line run\n\n`composer require butschster/lumen-microservice`\n\n#### Register Service provider\n```php\n// bootstrap.php\n$app-\u003eregister(Butschster\\Exchanger\\Providers\\ExchangeServiceProvider::class);\n```\n\n#### Copy config files from package `config` directory to your Lumen app and register them.\n\n```php\n$app-\u003econfigure('amqp');\n$app-\u003econfigure('microservice');\n$app-\u003econfigure('serializer');\n```\n\n#### Add variables to your .env file\n```\nMICROSERVICE_NAME=...\nMICROSERVICE_VERSION=1.0.0\nRABBITMQ_HOST=...\nRABBITMQ_USERNAME=...\nRABBITMQ_PASSWORD=...\nRABBITMQ_VHOST=...\nJWT_SECRET=...\n```\n\n#### Create exchange point in your app\nThis point will use for receiving request from other services and for sending responses.\n\n```php\nnamespace App\\Exchange\\Point;\n\nuse Butschster\\Exchanger\\Contracts\\Exchange\\Point as PointContract;\nuse Psr\\Log\\LoggerInterface;\nuse Butschster\\Exchanger\\Contracts\\Exchange\\IncomingRequest;\n\nclass Point implements PointContract\n{\n    public function getName(): string\n    {\n        return 'com.test';\n    }\n\n    /**\n     * @subject com.test.action.test\n     */\n    public function testSubject(IncomingRequest $request, LoggerInterface $logger)\n    {\n        $logger-\u003einfo(\n            sprintf('info [%s]:', $request-\u003egetSubject()),\n            [$request-\u003egetBody()]\n        );\n\n        // Response\n        $payload = new ...;\n        $request-\u003esendResponse($payload);\n\n        // or\n        $request-\u003esendEmptyResponse();\n\n        // or\n        $request-\u003eacknowledge();\n    }\n\n    /**\n     * @subject com.test.action.test1\n     */\n    public function anotherTestSubject(IncomingRequest $request, LoggerInterface $logger)\n    {\n        $payload = new ...;\n        $request-\u003esendResponse($payload);\n    }\n}\n```\n\nThen register this point\n\n```php\nuse App\\Exchange\\Point;\nuse Illuminate\\Support\\ServiceProvider;\nuse Butschster\\Exchanger\\Contracts\\Exchange\\Point as PointContract;\n\nclass AppServiceProvider extends ServiceProvider\n{\n    public function register()\n    {\n        $this-\u003eapp-\u003esingleton(PointContract::class, Point::class);\n    }\n}\n```\n\n#### Register console command\n```php\nuse Butschster\\Exchanger\\Console\\Commands\\RunMicroservice;\n\nclass Kernel extends ConsoleKernel\n{\n    protected $commands = [\n        RunMicroservice::class\n    ];\n}\n```\n\n#### Sending requests\nFor requesting information from another service you should use `ExchangeManager`\n\n```php\nuse Butschster\\Exchanger\\Contracts\\ExchangeManager;\n\nclass UserController {\n\n    public function getUser(ExchangeManager $manager, int $userId)\n    {\n        $requestPayload = new GetUserByIdPayload($userId);\n\n        $request = $manager-\u003erequest('com.test.action.test', $requestPayload);\n        $user = $request-\u003esend(UserPayload::class);\n\n        // You can set delivery mode to persistent\n        $user = $request-\u003esend(UserPayload::class, true);\n    }\n}\n\n// User Request Payload\n\nuse JMS\\Serializer\\Annotation\\Type;\n\nclass GetUserByIdPayload implements \\Butschster\\Exchanger\\Contracts\\Exchange\\Payload\n{\n    /** @Type(\"string\") */\n    public string $userId;\n    public function __construct(string $userId)\n    {\n        $this-\u003euserId = $userId;\n    }\n}\n\n// User Payload\n\nuse JMS\\Serializer\\Annotation\\Type;\n\nclass UserPayload implements \\Butschster\\Exchanger\\Contracts\\Exchange\\Payload\n{\n    /** @Type(\"string\") */\n    public string $id;\n\n    /** @Type(\"string\") */\n    public string $username;\n\n    /** @Type(\"string\") */\n    public string $email;\n\n    /** @Type(\"Carbon\\Carbon\") */\n    public \\Carbon\\Carbon $createdAt;\n}\n```\n\n#### Broadcasting\nIf you want to send an event you should use `ExchangeManager` method `broadcast`\n\n```php\nuse Illuminate\\Http\\Request;\nuse Butschster\\Exchanger\\Contracts\\ExchangeManager;\n\nclass UserController {\n\n    public function update(ExchangeManager $manager, Request $request, User $user)\n    {\n        $payload = new UserPayload();\n        $data = $request-\u003evalidate(...);\n        $user-\u003eupdate($data);\n\n        $payload-\u003eid = $user-\u003eid;\n        $payload-\u003eusername = $user-\u003eusername;\n        ...\n        \n        $manager-\u003ebroadcast('com.user.event.updated', $payload);\n\n        // You can set delivery mode to persistent\n        $manager-\u003ebroadcast('com.user.event.updated', $payload, true);\n    }\n}\n```\n\n#### Entity mapping\nYou can configure entity mapping in `serializer.php` config.\n\n```php\n// serializer.php\nreturn [\n    'mapping' =\u003e [\n        Domain\\User\\Entities\\User::class =\u003e [\n            'to' =\u003e Payloads\\User::class,\n            'attributes' =\u003e [\n                'id' =\u003e ['type' =\u003e 'string'],\n                'username' =\u003e ['type' =\u003e 'string'],\n                'email' =\u003e ['type' =\u003e 'string'],\n                'balance' =\u003e ['type' =\u003e Domain\\Billing\\Money\\Token::class],\n                'createdAt' =\u003e ['type' =\u003e \\Carbon\\Carbon::class],\n            ]\n        ],\n        Domain\\Billing\\Money\\Token::class =\u003e [\n            'to' =\u003e Payloads\\Billing\\Token::class,\n            'attributes' =\u003e [\n                'amount' =\u003e ['type' =\u003e \\Brick\\Math\\BigDecimal::class],\n            ]\n        ],\n    ],\n    // ...\n];\n```\n\nAnd then you can easily convert entities to payloads\n\n```php\nuse Butschster\\Exchanger\\Contracts\\Serializer\\ObjectsMapper;\n\nclass UserController {\n\n    public function update(ObjectsMapper $mapper, ExchangeManager $manager, Request $request, Domain\\User\\Entities\\User $user)\n    {\n        $data = $request-\u003evalidate(...);\n        $user-\u003eupdate($data);\n        \n        $payload = $mapper-\u003etoPayload($user);\n        \n        $manager-\u003ebroadcast('com.user.event.updated', $payload);\n    }\n}\n```\n\n#### Custom types\nIf you want to use custom JMS Serializer types you should use handlers. They can be added in `serializer.php` config.\n\n```php\n// serializer.php\nreturn [\n    'handlers' =\u003e [\n        Butschster\\Exchanger\\Jms\\Handlers\\CarbonHandler::class,\n        Infrastructure\\Microservice\\Jms\\Handlers\\BigDecimalHandler::class\n    ],\n    // ..\n];\n\n// BigDecimalHandler.php\n\nnamespace Infrastructure\\Microservice\\Jms\\Handlers;\n\nuse Brick\\Math\\BigDecimal;\nuse Butschster\\Exchanger\\Contracts\\Serializer;\nuse Butschster\\Exchanger\\Contracts\\Serializer\\Handler;\nuse JMS\\Serializer\\GraphNavigatorInterface;\nuse JMS\\Serializer\\Handler\\HandlerRegistryInterface;\n\nclass BigDecimalHandler implements Handler\n{\n    public function serialize(Serializer $serializer, HandlerRegistryInterface $registry): void\n    {\n        $registry-\u003eregisterHandler(\n            GraphNavigatorInterface::DIRECTION_SERIALIZATION,\n            BigDecimal::class,\n            'json',\n            function ($visitor, BigDecimal $value, array $type) {\n                return $value-\u003etoInt();\n            }\n        );\n    }\n\n    public function deserialize(Serializer $serializer, HandlerRegistryInterface $registry): void\n    {\n        $registry-\u003eregisterHandler(\n            GraphNavigatorInterface::DIRECTION_DESERIALIZATION,\n            BigDecimal::class,\n            'json',\n            function ($visitor, $value, array $type) {\n                return BigDecimal::of($value);\n            }\n        );\n    }\n}\n```\n\n#### Service running\nThis single command will run your microservice and start listening to commands registered in your exchange point.  \n\n`php artisan service:run`\n\nSupervisor is a process monitor for the Linux operating system, and will automatically restart your horizon process if it fails.\nTo install Supervisor on Ubuntu, you may use the following command:\n\n`sudo apt-get install supervisor`\n\nSupervisor configuration files are typically stored in the /etc/supervisor/conf.d directory. \nWithin this directory, you may create any number of configuration files that instruct supervisor how your processes should be monitored.\nFor example, let's create a microservice.conf file that starts and monitors a process:\n\n```\n[program:microservice]\nprocess_name=%(program_name)s\ncommand=php /var/www/app.com/artisan service:run\nautostart=true\nautorestart=true\nredirect_stderr=true\nstdout_logfile=/var/www/app.com/storage/logs/microservice.log\nstopwaitsecs=3600\n```\n\nOnce the configuration file has been created, you may update the Supervisor configuration and start the processes using the following commands:\n\n```\nsudo supervisorctl reread\n\nsudo supervisorctl update\n\nsudo supervisorctl start microservice\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbutschster%2Flumenmicroservice","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbutschster%2Flumenmicroservice","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbutschster%2Flumenmicroservice/lists"}