Download the PHP package othyn/laravel-notes without Composer

:notebook_with_decorative_cover: Table of Contents

• About the Project
  • Tech Stack
  • Features
• Install
  • Version Matrix
• Usage
  • Configuration
  • Models
• Contributing
  • Project Tooling Quick Reference
• Changelog
• License
• Acknowledgements

:star2: About the Project

On a recent personal project, I was finding that I was utilising a notes field against practically all tables, with the functionality also shared. The idea being that the user could quickly leave notes against any entity in the system, in which centralising that saves a load of overhead in each table and repeat code. I also make use of a shared Livewire table that automatically loads Audit's (in which the awesome design of that package inspired this one) for a given Entity when viewing it. The table is automatically injected into the rendered view determined automatically by the URL slug, which was a perfect use case to replicate for the notes system, thus this library was born.

:space_invader: Tech Stack

• Language: PHP
• Dependency Manager: Composer
• Framework: Laravel
• Package: illuminate/support
• Package: orchestra/testbench
• Package: pestphp/pest
• Package: phpunit/phpunit
• Package: friendsofphp/php-cs-fixer

:dart: Features

• Centralised note store against any Model entity
• Saves replicating repetitive fields and functionality across many tables
• Quickly apply the functionality to any Model with an interface and trait combo
• Easily overridable User resolver for custom auth scenarios
• Highly customisable and overridable
• Up and running in minutes

Future addition ideas to play around with:

• Some form of automated (customisable) injectable component for Blade and/or Livewire with backed CRUD functionality.
• Expanding this out to quickly capture any set of recurring fields out across all tables with ease, could be an interesting project enhancement

:floppy_disk: Install

Installation can be done via Composer:

Then publish the configuration file and migration(s) into your application scope via:

Remember to check the default configuration aligns with your requirements (amending if necessary) and run your migrations to generate the new notes table!

Next you are going to want to head down to the configuration, so lets get started on usage! See you there.

Version Matrix

Here is the current version matrix for project supported versions of used frameworks and libraries.

If you require support for an older version of Laravel, submit an issue as we may be able to look into dropping the version requirements down, as I don't think it needs to be this new. Or, feel free to submit a PR!

:hammer_and_wrench: Usage

Laravel Notes is simple in its implementation, to get started all you need to do is add the relevant interface and trait combo the Model you wish to store notes against.

:elephant: Models

So, you want to use Laravel Notes eh? I like you, lets get cooking. All you need to do is add the relevant interface and trait combo the Model you wish to store notes against:

That's it!

The following methods and properties will be exposed against the model:

As we are dealing with native Laravel relationships, all the usual Eloquent stuff also applies against the relationship method that is used:

This is what the default Note entity looks like, for easy property reference:

As you can see, there is IDE type hinting baked into the Contracts and default Model to assist with method and property discovery for all of the above.

If you need to go beyond that and really turn things up to 11, lets touch on what the configuration can do for you.

:wrench: Configuration

Given we published the configuration as part of the installation, you should now have an config/laravel-notes.php file within your project that you can edit. Below is a little detail on what each configuration option means and what it can do for you.

• note
  • Type: \Othyn\LaravelNotes\Contracts\Note
  • Default: \Othyn\LaravelNotes\Models\Note::class
  • Description:
    • The Model instance to use to refer to a Note, that implements \Othyn\LaravelNotes\Contracts\Note.
    • You can make use of the \Othyn\LaravelNotes\Traits\Note trait to implement base functionality if desired in any custom implementation you make.
• auth.guards
  • Type: array<string>
  • Default: ['web', 'api']
  • Description:
    • The Laravel Auth guards that should be polled to determine the logged in User to bind to the Note.
• auth.user.field_prefix
  • Type: string
  • Default: user
  • Description:
    • The polymorphic relationship field prefix, will be used as {field_prefix}_id and {field_prefix}_type within the notes table.
• auth.user.resolver
  • Type: \Othyn\LaravelNotes\Contracts\UserResolver
  • Default: \Othyn\LaravelNotes\Resolvers\UserResolver::class
  • Description:
    • The object that should resolve the Authenticatable Entity that will be bound to the Note, the id of the entity is all that matters.
    • You can easily implement your own resolver using the \Othyn\LaravelNotes\Contracts\UserResolver contract.
    • Must return an instance of \Illuminate\Contracts\Auth\Authenticatable or null as the user value.
• database.connection
  • Type: string
  • Default: config('database.default')
  • Description:
    • The database connection that should be used for all notes related activity.
    • When determining the default value, it will be read from the LARAVEL_NOTES_CONNECTION environment variable first, before reading the Laravel default database.default config value.
• database.table
  • Type: string
  • Default: notes
  • Description:
    • The database table that should be used for notes storage.
    • When determining the default value, it will be read from the LARAVEL_NOTES_TABLE environment variable first, before setting it to the pre-defined default value specified above.

That's it! Want to contribute? Keep reading.

:bread: Contributing

See the contribution guide on how to get started. Thank you for contributing!

:toolbox: Project Tooling Quick Reference

There are only a few project commands, and it's the usual stuff:

That's about it, go make something cool and submit a PR!

:warning: License

Distributed under the MIT License. See LICENSE for more information.

:gem: Acknowledgements

Useful resources and libraries that have been used in the making of this project.

• Readme: Louis3797/awesome-readme-template
• Readme: ikatyang/emoji-cheat-sheet
• Readme: shields.io
• Logo: Tag SVG Vector 242
  • From the Cube Icon Collection
  • Licenced under the CC Attribution License
• Starter: Laravel Package Boilerplate
• Inspiration: owen-it/laravel-auditing