{"id":20254195,"url":"https://github.com/fumeapp/humble","last_synced_at":"2025-04-10T23:50:30.468Z","repository":{"id":45124672,"uuid":"146867127","full_name":"fumeapp/humble","owner":"fumeapp","description":"passwordless authentication and detailed sessioning for laravel","archived":false,"fork":false,"pushed_at":"2025-02-17T17:32:32.000Z","size":97,"stargazers_count":14,"open_issues_count":2,"forks_count":4,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-24T20:38:13.210Z","etag":null,"topics":["authentication","laravel","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/fumeapp.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}},"created_at":"2018-08-31T08:54:58.000Z","updated_at":"2025-03-04T17:25:21.000Z","dependencies_parsed_at":"2024-04-25T07:24:59.147Z","dependency_job_id":"3abba123-408b-40e8-b707-5e1a9760258c","html_url":"https://github.com/fumeapp/humble","commit_stats":{"total_commits":88,"total_committers":2,"mean_commits":44.0,"dds":0.1477272727272727,"last_synced_commit":"ac1dc0d7e472eed804d2caad963dafc4230a3f2b"},"previous_names":[],"tags_count":56,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fumeapp%2Fhumble","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fumeapp%2Fhumble/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fumeapp%2Fhumble/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fumeapp%2Fhumble/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fumeapp","download_url":"https://codeload.github.com/fumeapp/humble/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247895769,"owners_count":21014381,"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":["authentication","laravel","php"],"created_at":"2024-11-14T10:30:38.343Z","updated_at":"2025-04-10T23:50:30.451Z","avatar_url":"https://github.com/fumeapp.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/fumeapp/humble/raw/master/logo.jpg\"/\u003e\n\u003c/p\u003e\n\n\u003e Ideal Sessioning and authentication for Laravel\n\n[![Packagist License](https://poser.pugx.org/acidjazz/humble/license.png)](https://choosealicense.com/licenses/apache-2.0/)\n[![Latest Stable Version](https://poser.pugx.org/acidjazz/humble/version.png)](https://packagist.org/packages/acidjazz/humble)\n[![Total Downloads](https://poser.pugx.org/acidjazz/humble/d/total.png)](https://packagist.org/packages/acidjazz/humble)\n\n## Features\n* Passwordless authentication\n  * Ability to store and compare a cookie, securing the magic link sent out\n  * Link expiration\n  * Able to store \"action\" objects passed through for completing tasks the user was doing before prompted\n* Detailed sessions using [whichbrowser](https://github.com/WhichBrowser/Parser-PHP)\n\n```json\n\"device\": {\n  \"string\": \"Chrome 68 on a Google Pixel 2 XL running Android 9\",\n  \"platform\": \"Android 9\",\n  \"browser\": \"Chrome 68\",\n  \"name\": \"Google Pixel 2 XL\",\n  \"desktop\": false,\n  \"mobile\": true\n}\n```\n\n* Detailed location using [lyften](https://github.com/Torann/laravel-geoip)'s adapter for [GeoIP2](https://github.com/maxmind/GeoIP2-php)\n\n```json\n\"location\": {\n  \"ip\": \"86.222.88.167\",\n  \"country\": \"France\",\n  \"city\": \"Lons\",\n  \"state\": \"NAQ\",\n  \"postal_code\": \"64140\",\n  \"lat\": 43.3167,\n  \"lon\": -0.4,\n  \"timezone\": \"Europe\\/Paris\",\n  \"currency\": \"EUR\"\n}\n```\n\n## Installation\n\nInstall humble with [composer](https://getcomposer.org/doc/00-intro.md):\n```bash\ncomposer require acidjazz/humble\n```\n\nAdd Humble's trait to your user model:\n\n```php\nuse Fumeapp\\Humble\\Traits\\Humble;\n...\nclass User extends Authenticatable\n{\n  use Humble, Notifiable;\n}\n```\n\n### Publish Humble's migrations (sessions table)\n```bash\nphp artisan vendor:publish --tag=\"humble.migrations\"\n```\n\nRun the migration\n```bash\nphp artisan migrate\n```\n\nChange your guard in your config, to the 'humble' guard in `config/auth.php`, in my case since I mainly use Laravel as an API\n```php\n    'guards' =\u003e [\n        'web' =\u003e [\n            'driver' =\u003e 'session',\n            'provider' =\u003e 'users',\n        ],\n\n        'api' =\u003e [\n            'driver' =\u003e 'humble',\n            'provider' =\u003e 'users',\n        ],\n    ],\n```\n\u003e Check your defaults as well, if it's not api, you'll need to change that\n\nIf your user class is not `App\\Models\\User`, we need to tell humble what it is:\n\n### Publish Humble's configuration\n```\n php artisan vendor:publish --tag=\"humble.config\"\n```\nModify `config/humble.php` and specify your user class\n\n## Usage\n\nHumble is similar to [Laravel Sanctum](https://laravel.com/docs/9.x/sanctum#introduction) in the way you can also assign abilties to sessions.\n\nPrimarily humble sessions are stored for user sessions which by default would inherit all session abilities. You can also think of Humble Session as Personal Access Tokens, inside your application your users could create multiple session tokens for various services and integrations like: GitHub actions, CLI Applications, Slack Tokens, etc...\n\nWith these addtional session tokens your users can create, you still have access to the session `source` where you can attach certain Gates \u0026 Policy behaviors based on that. If your are fine with leaving these session tokens as-is with same access as the user you can stick with that. If you need more granularity you can also assign abilites.\n\nWith abilites you can addtionally set specific rules these session tokens can have. For example you might want to have a session tokens for a GitHub action that only has the abilty to peform READ events and not WRITE.\n\nThese abilites can be user defined in your app, meaing its up to you to declare these rules in your app and check/valdiate them. The default ability is set to \n`[\"*\"]` which means full access, but when creating a session you can pass a parameter to only set this to READ, and which your database record would show as \n`[\"READ\"]`\n\nFor valdiating these abilites we provide a few helpers and middlewares to make this easier.\n\nTo validate the middleware level you first need to add the following to your `$routeMiddleware` inside of `app/Http/Kernel.php`\n\n```php\n// ...\n'abilities' =\u003e \\Fumeapp\\Humble\\Http\\Middleware\\CheckAbilities::class,\n'ability' =\u003e \\Fumeap\\Humble\\Http\\Middleware\\CheckForAnyAbility::class,\n// ...\n```\n\nOnce you add those, you can apply them in your routes middleware like so:\n\n```php\nRoute::get('admin', function () {\n    return response()-\u003ejson([\n        'success' =\u003e true\n    ]);\n})-\u003emiddleware(['auth:api', 'ability:admin']);\n```\n\n\u003e The example would pass if that session token had the abilites as: `[\"*\"]` or `[\"admin\"]`\n\nYou can also use `abilities` as middleware which is a strict check that the token must have all the given abilites.\n\nOther ways of checking/valdiating abilites inside of your app in areas like Gates \u0026 Polciies\n\n1. `auth()-\u003euser()-\u003etokenCan('write')`\n2. `auth()-\u003esession()-\u003ecan('write')`\n3. `$user()-\u003etokenCan('write')`\n4. `$request-\u003euser()-\u003etokenCan('write')`\n\n\nWe also provide an easy way to create new session tokens with the following method\n\n```php\n $user-\u003ecreateToken('action', ['write'])\n```\n\n\u003e This would also work with either `auth()-\u003euser()-\u003ecreateToken(...)` or `$request-\u003euser()-\u003ecreateToken(...)`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffumeapp%2Fhumble","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffumeapp%2Fhumble","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffumeapp%2Fhumble/lists"}