README

A simple starter kit for the Laravel framework.

Hearth is a simple starter kit for the Laravel framework. It provides a few things out of the box:

A user model with login, registration, email verification
Optional two-factor authentication support for users.
An organization model.
A membership model which reflects users' roles within organizations.
An invitation model which allows users to be invited to join organizations.
A resource model supporting creation of and access to a library of open educational resources in a wide range of formats.
Multilingual support, including localized routes.
Bare bones views which can be published and customized as needed.

Installation

Hearth requires PHP >= 8.2 and Laravel >= 10.

You may use Composer to install Hearth into your new Laravel project:

composer require fluid-project/hearth

Note: attempting to install Hearth into an existing Laravel application will result in unexpected behaviour.

After installing the Hearth package, you can use the hearth:install Artisan command to install the Hearth scaffolding within your Laravel application:

php artisan hearth:install

After installing Hearth, you will need to install and build your NPM dependencies, run your database migrations and link public storage:

npm install
php artisan migrate
php artisan storage:link

Emails

In order to test emails (for example, using Mailhog with Laravel Sail), you must update your Laravel application's .env file's MAIL_FROM_ADDRESS environment variable with a properly-formatted email address. For local development, this might be noreply@hearth.test (assuming your local application is accessible at http://hearth.test).

Usage

TODO.

Formatting

To format your code using Laravel Pint, you can run:

composer format

This should be done prior to each commit, or at least prior to opening a pull request.

Testing

Prior to testing, you will need to create a MySQL or MariaDB database for testing with credentials which match those in phpunit.xml.dist. Then run:

composer test

You can get code coverage results if XDebug is installed by running:

composer test-coverage

To test the code located in the stubs directory you'll need to install Hearth into a Laravel instance and run the tests from there.

Analysis/Linting

The code should pass level 5 testing.

composer analyze

To analyze the code located in the stubs directory you'll need to install Hearth into a Laravel instance and run the analysis from there. The phpstan configuration is provided as part of the install, but Larastan will need to be manually installed.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The BSD 3-Clause License. Please see License File for more information.

Third Party Software in Hearth

Hearth is based on other publicly available software, categorized by license:

fluid-project / hearth

Maintainers

Details