Skip to content
No description, website, or topics provided.
PHP HTML Vue Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
app
bin
bootstrap
config
database
public
resources
routes
storage
tests
.editorconfig
.env.example
.gitattributes
.gitignore
.styleci.yml
Vagrantfile
after.sh
artisan
composer.json
package-lock.json
package.json
phpunit.dusk.xml
phpunit.xml
readme.md
server.php
webpack.mix.js

readme.md

This code is under active development and not stable for production use! If you're feeling super brave, then by all means give it a try. But if you just want to use MonkeyPod, you should probably go with the hosted version.

MonkeyPod Application Scaffolding

Open-source, laravel-based application for nonprofit accounting and other management tools.

Here be dragons!

Setting up and running this application requires extensive experience with Laravel along with general technical expertise. This is not a one-click install-and-run situation like Wordpress. This code provides a foundation to build on for your own application, but is not plug-n-play. If those sentences are intimidating rather than exciting, then you'll be better off using the hosted service, which takes 5-minutes to set up and includes lots of additional bells and whistles.

Installation Checklist

For the purposes of this checklist we'll assume you're using GitHub for source control, but these instructions could easily be adapted if you prefer something else. We'll also assume that you're using Laravel Homestead or another server setup that is fully equipped and configured for Laravel. Steps like installing a database and configuring nginx are beyond the scope of these instructions.

  • Setup a new Git repository for your application. (We'll call it "myapp" here.)

  • Pull down the app from GitHub:

    • git init myapp
    • cd myapp && git pull git@github.com:monkeypod-io/app.git
  • Set your project as the remote origin:

    • git remote add origin git@github.com:[YourUser]/myapp.git
  • Set the official distribution as the upstream remote (this will allow you to pull in changes from future versions):

    • git remote add upstream git@github.com:monkeypod-io/app.git
  • Install composer dependencies:

    • composer install
  • Install npm dependencies:

    • npm install
  • Compile assets:

    • npm run [dev|prod]
  • Create .env file:

    • cp .env.example .env
  • Generate application key

    • php artisan key:generate
  • Configure database environment variables in .env

  • Configure your organization settings:

    • config/monkeypod.php
  • Publish vendor assets (minimally migrations, but anything else you'd like to customize):

    • php artisan vendor:publish
  • Migrate and seed the database:

    • php artisan migrate && php artisan db:seed
  • Sign up for 3rd-party services on which MonkeyPod relies and configure .env variables accordingly:

    • ALGOLIA_* — Sign up for Algolia and enter your API credentials
    • PUSHER_* — Sign up for Pusher and enter your API credentials
    • AWS_* — Sign up for AWS and enter your API credentials and other settings
    • GOOGLE_* — Optionally, add Google Analytics credentials
  • Configure remaining environment variables in .env

  • Create an initial admin user account:

    • php artisan make:admin

Customizing or Extending MonkeyPod

The strongly recommended way to extend or customize MonkeyPod is through the use of modules. This will keep your changes isolated and make it easier to stay up to date with changes in the main app. Speaking of which...

Modules

MonkeyPod modules extend the basic functionality with additional capabilities. Current official modules include:

More official modules are in the works. In the meantime, you can always create your own, in which case we'd love to hear about it!

How Modules Work

MonkeyPod's module system is built on the excellent laravel-modules package by Nicolas Widart. Before attempting to develop or modify a MonkeyPod module, you should have a basic understanding of how laravel-modules works by default. However, MonkeyPod uses a few of its own conventions and adds some additional features. Mostly these relate to adding or extending core functionality.

By using basic laravel-modules functionality, MonkeyPod modules can add:

  • models and associated policies, observers, validators, etc.
  • routes, controllers, and related Http classes
  • services
  • views and related assets
  • tabs to qualified existing views
  • etc.

MonkeyPod-specific module behavior goes a bit further:

Configuration Merging

MonkeyPod relies on several different application configuration files, all of which can be extended by modules. These include:

  • monkeypod-actions — Actions that apply to specific models, such as "Edit", or "Delete", or "Re-activate"
  • monkeypod-navigation — The application's main navigation menus
  • monkeypod-permissions — Default role-based permissions for use by policy authorizations
  • monkeypod-tabs ‐ Tabbed-views
  • monkeypod-validation — Model-level validation rules and messages

MonkeyPod modules may define their own actions.php, permissions.php, tabs.php, and validation.php config files, which will be merged recursively with the application's configuration. This allow modules to inject content and behaviors into core application logic without having to touch any code outside the module itself. To add additional navigation menus, you can edit the monkeypod-navigation.php file and reference whatever additional navigation classes you like.

Deeper Modification of Core Behavior

Unfortunately, it isn't always possible to meet a module's requirements through configuration alone. Sometimes we need to extend or supplement the capabilities of a MonkeyPod/Core model, for example. This should be done sparingly and with caution, as it introduces the potential for conflicts and confusing, unmaintainable code. That caveat aside, the preferred mechanism for addressing this situation is a series of "ExtendsXYZ" traits that live in the app\Models\Concerns\Extended directory. Modules may include their own traits, which must be manually added to the relevant "extender traits" as part of the installation process.

NOTE: Future versions of MonkeyPod will likely abandon this convention in favor of decorators or another cleaner approach.

Module Compatibility

When you have a half-dozen modules all trying to cohabitate peacefully, it can be difficult to keep track of overlapping dependencies. MonkeyPod uses semantic version (with its own twist) to try to bring some order to this chaos.

Pre 1.0 Versions

Any versions in the 0.X.Y range should be considered unstable and under active development. Generally speaking, if there is a release number at all, then someone is using the code somewhere. But especially at the lower ends of this version range, you should assume that the code is liable to change at any time, including basic APIs, interfaces, etc. If you are using pre-1.0 MonkeyPod code, make sure you have sufficient test coverage to spot any breakages before they are deployed.

Stable Versions

Starting at 1.0.0, MonkeyPod code should be considered relatively stable. We aim to follow semantic versioning conventions, whereby bugfixes bump the patch number, new features bump the minor number, and breaking changes bump the major number.

MonkeyPod departs from strict semantic versioning, however, in the interest of making it easier to keep track of inter-module compatability. To that end, module developers should make sure that all releases in a particular major version range should be compatible with the monkeypod/app and monkeypod/core releases in the same major version range. If this principle is respected, then cross-module compatability should not generally be an issue, since modules are designed to be totally isolated from each other.

You can’t perform that action at this time.