App Package

MetaFox Backend utilizes Laravel Service Providers (opens in a new tab) to provide a robust, re-useable, and flexible way to extend platform features.

App Directory Structure

The packages directory contains all packages and is organized as below:

packages/
    [vendor_name]/
        package-1/
        package-2/

vendor_name should be your company name to avoid duplication with others.

In the next section, we will look into details of app directory structure.

composer.json                : Package infomration and composer dependencies
config/                      :
  config.php                 : Contain package configuration
resources/                   :
  langs/
    en/                      : Language file for `en` locale
      phrase.php             : Define phrases for group `phrase`
      validator.php          : Define phrases for group `validator`
  menu/                      :
    menus.php                :
    menuitems.php            :
  routes/                    :
     api.php                 : Define RESTful API routes
     web.php                 : Define web routes
  src/
    Contracts/               : Contains basic interface defination
    Database/                :
      Factories              : Contain database model [factories](https://laravel.com/docs/9.x/database-testing#defining-model-factories)
      Migrations             : Contain database [migrations](https://laravel.com/docs/9.x/migrations#main-content)
      Seeders                : Contain database [seeders](https://laravel.com/docs/9.x/seeding#introduction)
        PackageSeeder.php    : Entry point for database seeder
  Http/
    Controllers/             :
    Requests/                :
    Resources/               :
  Jobs/                      :
  Listeners/                 :
  Mail/                      :
  Notification/              :
  Models/                    :
  Observers/                 :
  Policies/                  :
  Providers/                 :
  Repositories/              :
  Rules/                     :
  tests/                     :
    Features/                :
    Unit/                    :

composer.json

{
  "name": "metafox/video",
  "version": "5.0.7",
  "description": "",
  "authors": [
    {
      "name": "phpFox",
      "email": "[email protected]",
      "homepage": "https://www.phpfox.com"
    }
  ],
  "extra": {
    "metafox": {
      "core": false,
      "alias": "video",
      "asset": "video",
      "namespace": "MetaFox\\Video",
      "path": "packages/metafox/video",
      "title": "Video",
      "internalAdminUrl": "/video/setting",
      "providers": ["MetaFox\\Video\\Providers\\PackageServiceProvider"],
      "frontend": {
        "@metafox/video": "*"
      },
      "frontendPaths": ["packages/metafox/video"],
      "require": {
        "metafox/core": "5.1.3 - 5.1.4"
      },
      "aliases": {}
    }
  },
  "autoload": {
    "psr-4": {
      "MetaFox\\Video\\": "src/"
    }
  },
  "require": {
    "php-ffmpeg/php-ffmpeg": "^1.0"
  },
  "autoload-dev": {
    "psr-4": {
      "MetaFox\\Video\\": "",
      "MetaFox\\Video\\Tests\\": "tests/"
    }
  }
}

Base Information

Name

name: The name of the app package. It consists of vendor name and project name, separated by a slash (/)

For examples:

metafox/platform
metafox/blog

The app name MUST be lowercase and consist of words separated by -, . or _. The complete name should match the regular expression ^[a-z0-9]([_.-]?[a-z0-9]+)_/[a-z0-9](<([_.]?|-{0,2})[a-z0-9]+>)\_\$.

Description

description: A short description of the app package. Should be a one-line message.

Version

version: a string specifing the version of the app package. In most cases, this field is not required and can be omitted (see below).

Here are some examples of valid values for versions

1.0.0
1.0.2
1.1.0
0.2.5
1.0.0-dev
1.0.0-alpha3
1.0.0-beta2

Authors

authors: Info of the authors of the package. You can specify multiple author objects here. An author object can have following properties:

name: The author's name. Usually their real name.
email: The author's email address.
homepage: URL to the author's website.

Require

require: Map of packages required by this package. The app package will not be installed unless all requirements are met.

Require-Dev

require-dev: Map of packages required for developing this package, or running tests, etc. The dev requirements of the root package are installed by default. Both install and update commands support the --no-dev option to prevent dev dependencies from being installed.

Autoload

autoload.psr-4: Under the psr-4 key you can define a mapping from namespaces to paths relative to the package root. When autoloading a class like Foo\\Bar\\Baz, and a namespace prefixed Foo\\ are pointed to a directory src/, the autoloader will look for a file named src/Bar/Baz.php and include it if existing. Note that as opposed to the older PSR-0 style, the prefix (Foo\\) is not present in the file path.

Namespace prefixes must end in \\ to avoid conflicts between similar prefixes. For example: Prefix Foo would match classes in the FooBar namespace. Thus, we use the trailing backslashes to solve the problem: Foo\\ and FooBar\\ are distinct.

The PSR-4 references are all combined, during installation or update, into a single key which may be found in the generated file vendor/composer/autoload_psr4.php.

autoload.files: If you want to require certain files explicitly on every request then you can use the file autoloading mechanism. This is very useful if your app package needs to include PHP functions that cannot be autoloaded by PHP

{
  "autoload": {
    "files": ["src/MyLibrary/functions.php"]
  }
}

autoload-dev: This section allows to define autoload rules for development purposes.

Classes only running for testing purposes should not be included in the main autoload rules to optimize the autoloader in production or for others to use your app package as a dependency.

Therefore, it is a good solution to rely on a dedicated path for your unittests and add it within the autoload-dev section.

For example:

{
  "autoload": {
    "psr-4": { "MyLibrary\\": "src/" }
  },
  "autoload-dev": {
    "psr-4": { "MyLibrary\\Tests\\": "tests/" }
  }
}

MetaFox

MetaFox framework picks extra.metafox section for installation, exporting, upgrading, etc ...

Example of extra.metafox

{
  "extra": {
    "metafox": {
      "core": false,
      "alias": "video",
      "asset": "video",
      "namespace": "MetaFox\\Video",
      "path": "packages/metafox/video",
      "title": "Video",
      "internalAdminUrl": "/video/setting",
      "providers": ["MetaFox\\Video\\Providers\\PackageServiceProvider"],
      "frontend": {
        "@metafox/video": "*"
      },
      "frontendPaths": ["packages/metafox/video"],
      "require": {
        "metafox/core": "5.1.3 - 5.1.4"
      },
      "aliases": {}
    }
  }
}

metafox.path

extra.metafox.path is required. Used to indicate backend package source under root application. For example: packages/metafox/blog

metafox.alias

extra.metafox.alias is required. Used to indicate the alias name of your app package. For example, you may prefer to use an alias name blog rather than fully name metafox/blog.

metafox.namespace

extra.metafox.namespace is required. Used to indicate the root namespace of the package. It must use trailing backslashes with \\. For example: MetaFox\\Blog

metafox.internalAdminUrl

extra.metafox.internalAdminUrl is required. Used to indicate where to navigate when administrator click on the app in the AdminCP area.

metafox.frontend

extra.metafox.frontend is optional. Used to indicate frontend end packages.

metafox.frontendPaths

extra.metafox.frontendPaths is optional. Used to indicate frontend paths when developer export packages

metafox.peerDependencies

extra.metafox.peerDependencies is optional. Used to indicate peer dependencies backend packages when developer export packages.

The packages listed in peerDependencies comes with single exported file. It's helpful for developer release a product with multiple packages dependencies.

{
  "peerDependencies": ["metafox/payment-helpers"]
}

metafox.providers

extra.metafox.providers is optional. The array of fully Laravel provider classes, for futher information read out Service Provider (opens in a new tab)

Commands Controller