Skip to content

Commit d4ca605

Browse files
octoperoctoper
committed
initial release
1 parent 8ac3db4 commit d4ca605

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

41 files changed

+1326
-1
lines changed

‎build-a-standalone-application.md

+93
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
title: Build a standalone application
3+
description: Build a standalone PHAR archive to ease the deployment or distribution of your project
4+
---
5+
6+
# Build a standalone application
7+
8+
Your Laravel Zero project, by default, allows you to build a standalone PHAR archive to ease the deployment or distribution of your project.
9+
```bash
10+
php your-app-name app:build <your-build-name>
11+
```
12+
13+
The build will provide a single phar archive, ready to use, containing all the code of your project and its dependencies. You will then be able to execute it directly:
14+
```bash
15+
./builds/<your-build-name>
16+
```
17+
18+
or on Windows:
19+
```bash
20+
C:\application\path> php builds\<your-build-name>
21+
```
22+
23+
We use `humbug/box` to provide fast application bundling. In order to configure your build, you should take a look at the file `box.json`.
24+
25+
Please check the box documentation to understand all options: [github.com/humbug/box/blob/master/doc/configuration.md](https://github.com/humbug/box/blob/master/doc/configuration.md).
26+
27+
## Non-interactive build
28+
29+
When you build you get asked about build version, in case you want to skip this step you can provide the build version as an option:
30+
```bash
31+
php your-app-name app:build --build-version=<your-build-version>
32+
```
33+
34+
## Self update
35+
36+
Using the `app:install` Artisan command you can install the `self-update` component:
37+
```bash
38+
php <your-app-name> app:install self-update
39+
```
40+
41+
This component will add an Artisan `self-update` command to every build application. This command
42+
will try to download the latest version from GitHub, if available.
43+
44+
#### Custom update strategies
45+
46+
The self-updater supports custom "strategies" to configure how the application is updated. By default it uses the `GithubStrategy` which will try to download the PHAR binary from a `builds/` directory in the GitHub source repository.
47+
48+
Custom strategies must implement the following [`StrategyInterface` interface](https://github.com/laravel-zero/framework/blob/master/src/Components/Updater/Strategy/StrategyInterface.php).
49+
50+
By default, a few strategies are provided in Laravel Zero:
51+
52+
- Download the PHAR file from the `builds/` directory on GitHub:
53+
`LaravelZero\Framework\Components\Updater\Strategy\GitHubStrategy`
54+
- Download the PHAR file from GitHub releases assets:
55+
`LaravelZero\Framework\Components\Updater\Strategy\GitHubReleasesStrategy`
56+
57+
To use a custom strategy, first publish the config using:
58+
59+
```bash
60+
php <your-app-name> vendor:publish --provider "LaravelZero\Framework\Components\Updater\Provider"
61+
```
62+
63+
Then update the `updater.strategy` value in the configuration file to use the required class name.
64+
65+
## Environment Variables
66+
67+
If the `dotenv` component is installed, you can place a `.env` file in the same
68+
folder as the build application to make Laravel Zero load environment variables from
69+
that same file.
70+
71+
## Database
72+
73+
To use SQLite in your standalone PHAR application, you need to tell Laravel Zero where to place the database in a production environment.
74+
75+
Similar to Laravel, this is configured in `config/database.php` under the `connections.sqlite.database` key. By default this is set to `database_path('database.sqlite')` which resolves to `<project>/database/database.sqlite`. Since we can't modify files within the project once the PHAR is built, we need to store this somewhere on the users computer. A good choice for this would be to create a "dot" folder inside your users home folder. For example:
76+
77+
```diff
78+
// config/database.php
79+
'connections' => [
80+
'sqlite' => [
81+
'driver' => 'sqlite',
82+
'url' => env('DATABASE_URL'),
83+
- 'database' => database_path('database.sqlite'),
84+
+ 'database' => $_SERVER['HOME'] . '/.your-project-name/database.sqlite',
85+
'prefix' => '',
86+
'foreign_key_constraints' => env('DB_FOREIGN_KEYS', true),
87+
],
88+
]
89+
```
90+
91+
In this case it would tell Laravel to use the database at `/Users/<username>/.your-project-name/database.sqlite` (for MacOS).
92+
93+
It is important to note that this file will not exist upon installation of your app so you will either need to ensure it exists and is migrated before using the database or provide an `install` command which creates the database and migrates it.

‎build-interactive-menus.md

+69
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
title: Build interactive menus
3+
description: Build interactive menus
4+
---
5+
6+
# Build interactive menus
7+
8+
Using the `app:install` Artisan command you can install the `menu` component:
9+
```bash
10+
php <your-app-name> app:install menu
11+
```
12+
13+
Interactive menus in console applications are very powerful. They
14+
provide a simple interface that requires little interaction. With Laravel
15+
Zero, you can use the `menu` method to create beautiful menus:
16+
17+
Using menus in the console may sound silly, but is fantastic! Your users
18+
don't need to type the number corresponding to their choice any more. They
19+
can just use the arrows on their keyboard to make their selection!
20+
21+
#### Example
22+
23+
Create your first menu by copy pasting the code below in your commands
24+
`handle` function.
25+
26+
```php
27+
$option = $this->menu('Pizza menu', [
28+
'Freshly baked muffins',
29+
'Freshly baked croissants',
30+
'Turnovers, crumb cake, cinnamon buns, scones',
31+
])->open();
32+
33+
$this->info("You have chosen the option number #$option");
34+
```
35+
36+
When you now run your command your output should be similar to this
37+
image:
38+
39+
<img
40+
src="https://raw.githubusercontent.com/nunomaduro/laravel-console-menu/master/docs/example.png"
41+
class="md:w-4/5 md:mx-auto"
42+
>
43+
44+
<h4 class="mt-0">Changing the appearance</h4>
45+
46+
The appearance of the menu can be set with a fluent API. What if we like
47+
a green font on a black background? The code below shows you how to do just that and some extras.
48+
49+
```php
50+
$this->menu($title, $options)
51+
->setForegroundColour('green')
52+
->setBackgroundColour('black')
53+
->setWidth(200)
54+
->setPadding(10)
55+
->setMargin(5)
56+
->setExitButtonText("Abort")
57+
// remove exit button with
58+
// ->disableDefaultItems()
59+
->setUnselectedMarker('❅')
60+
->setSelectedMarker('✏')
61+
->setTitleSeparator('*-')
62+
->addLineBreak('<3', 2)
63+
->addStaticItem('AREA 2')
64+
->open();
65+
```
66+
67+
> Behind the scenes, the `menu` method uses the
68+
[`nunomaduro/laravel-console-menu`](https://github.com/nunomaduro/laravel-console-menu)
69+
package. You can find more details on how to use the menu method there.

‎commands.md

+90
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
title: Commands
3+
description: The `App\Commands` folder
4+
---
5+
6+
# Commands
7+
8+
The `App\Commands` folder should contain your application Artisan commands. By default,
9+
it brings the `app\Commands\InspiringCommand.php` as example command:
10+
```php
11+
namespace App\Commands;
12+
13+
use Illuminate\Console\Scheduling\Schedule;
14+
use LaravelZero\Framework\Commands\Command;
15+
16+
class InspiringCommand extends Command
17+
{
18+
/**
19+
* The signature of the command.
20+
*
21+
* @var string
22+
*/
23+
protected $signature = 'inspiring {name=Artisan}';
24+
25+
/**
26+
* The description of the command.
27+
*
28+
* @var string
29+
*/
30+
protected $description = 'Display an inspiring quote';
31+
32+
/**
33+
* Execute the console command.
34+
*
35+
* @return mixed
36+
*/
37+
public function handle()
38+
{
39+
$this->info('Simplicity is the ultimate sophistication.');
40+
}
41+
42+
/**
43+
* Define the command's schedule.
44+
*
45+
* @param \Illuminate\Console\Scheduling\Schedule $schedule
46+
* @return void
47+
*/
48+
public function schedule(Schedule $schedule)
49+
{
50+
// $schedule->command(static::class)->everyMinute();
51+
}
52+
}
53+
```
54+
55+
Of course, you can always create a new command using the `make:command` Artisan command:
56+
```bash
57+
php <your-app-name> make:command <NewCommand>
58+
```
59+
60+
The `signature` property should contain the definition of the input expectations. This is the place
61+
to define how to gather input from the user through arguments or options:
62+
```php
63+
protected $signature = 'user:create
64+
{name : The name of the user (required)}
65+
{--age= : The age of the user (optional)}'
66+
```
67+
68+
For more information, check out the [Defining Input Expectations](https://laravel.com/docs/artisan#defining-input-expectations)
69+
on the Laravel Documentation.
70+
71+
The `description` property should contain one line description of your command's job. Later, this description is
72+
used on the application list of commands.
73+
74+
The `handle` method is the place where the logic of your command should be. This method will be called when your
75+
command is executed. Note that we are able to inject any dependencies we need into the `handle` method:
76+
```php
77+
public function handle(Service $service)
78+
{
79+
$service->execute('foo');
80+
81+
$this->info('Operation executed');
82+
}
83+
```
84+
85+
The [Command I/O](https://laravel.com/docs/artisan#command-io) topic in the Laravel Documentation, can help
86+
you to understand how to capture those input expectations and interact with the user using commands
87+
like `line`, `info`, `comment`, `question` and `error` methods.
88+
89+
The `schedule` method allows to define the command's schedule. Please head over to the
90+
topic [Task Scheduling](/docs/task-scheduling) to find more information about this method.

‎configuration.md

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
title: Configuration
3+
description: The `config` folder
4+
---
5+
6+
# Configuration
7+
8+
The `config` folder should contain your application config files. Files in this folder
9+
are automatically registered as configuration files. As example, if you create an `config/bar.php`,
10+
you can access it using `config('bar')`.
11+
12+
The configuration files `config/app.php` and `config/commands.php` are used internally by the
13+
framework, and can not be removed.
14+
15+
The `config/app.php` contains information related to your application:
16+
17+
| Property | Description
18+
| ------------- | -------------
19+
| name | This value is the name of your application
20+
| version | This value determines the "version" your application is currently running in.
21+
| env | This value determines the "environment" your application is currently running in.
22+
| providers | The service providers listed here will be automatically loaded on your application.
23+
24+
The default command of your application contains a list of commands. That list of commands
25+
can be configured using `config/commands.php`:
26+
27+
| Property | Description
28+
| ------------- | -------------
29+
| default | The default application command when no command name is provided.
30+
| paths | The "paths" that should be loaded by the console's kernel.
31+
| add | Here you may specify which commands classes you wish to include.
32+
| hidden | Adds the provided commands, but make them hidden.
33+
| remove | Removes the list of commands provided.
34+
35+
### Disabling default component providers
36+
37+
The Database, Log, and Queue components support disabling auto-loading for their
38+
default service provider to allow the use of a custom provider.
39+
40+
To disable the default service provider for a component, set the `useDefaultProvider` value
41+
to `false` in the configuration file. You can then add your custom `ServiceProvider` class
42+
to the `app.providers` configuration array.

‎contributing.md

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
title: Contributing
3+
description: How to contribute
4+
---
5+
6+
# Contributing
7+
8+
Everything that we make is 100% open source and developed collaboratively by people from all over the world. Even if you're not a programmer, you can get involved and make a difference.
9+
10+
#### Code
11+
12+
You may propose new features or improvements of existing Laravel Zero behavior. If you propose a new feature, please be willing to implement at least some of the code that would be needed to complete the feature.
13+
14+
The Laravel Zero source code is managed on GitHub, and there are repositories for each of the Laravel Zero projects:
15+
16+
- [Laravel Zero Application](https://github.com/laravel-zero/laravel-zero)
17+
- [Laravel Zero Framework](https://github.com/laravel-zero/framework)
18+
- [Laravel Zero Installer](https://github.com/laravel-zero/installer)
19+
- [Laravel Zero Website](https://github.com/laravel-zero/website)
20+
- [Collision](https://github.com/nunomaduro/collision)
21+
22+
All the contribution guidelines are mentioned [here](https://github.com/laravel-zero/laravel-zero/blob/master/CONTRIBUTING.md).
23+
24+
You can have a look at the [CHANGELOG](https://github.com/laravel-zero/laravel-zero/blob/master/CHANGELOG.md) for constant updates & detailed information about the changes. You can also follow the twitter account for latest announcements : [@enunomaduro](https://twitter.com/enunomaduro)
25+
26+
#### Funding
27+
28+
My name is Nuno Maduro and I am the creator and maintainer of tools such as Laravel Zero, Collision, etc.
29+
30+
All my work has always been released under the Open Source license MIT, and this will continue into the far future. It has cost me thousands of hours to develop, test and support Laravel Zero, Collision, etc.
31+
32+
If you find the work I do for the PHP community valuable then you can show your appreciation by supporting me here on Patreon or Paypal.
33+
34+
The support will be used to create new features and everything related to make the console development the most enjoyable as possible.
35+
36+
- PayPal: [Donate](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=66BYDWAT92N6L)
37+
- Patreon: [Donate](https://www.patreon.com/nunomaduro)
38+
- Open Collective: [Donate](https://opencollective.com/laravel-zero)
39+
40+
#### License
41+
42+
Laravel Zero is an open-source software licensed under the MIT license.

‎create-a-logo.md

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: Create a logo
3+
description: Create a logo
4+
---
5+
6+
# Create a logo
7+
8+
Using the `app:install` Artisan command you can install the `logo` component:
9+
```bash
10+
php <your-app-name> app:install logo
11+
```
12+
13+
Just after installation, if you run `php <your-app-name>` your application will contain
14+
a ASCII logo:
15+
16+
<img
17+
src="https://raw.githubusercontent.com/laravel-zero/docs/master/images/logo.png"
18+
class="md:w-4/5 md:mx-auto"
19+
>
20+
21+
This command will install dependencies needed and publishes a config file under `config/logo.php`.
22+
23+
### Using a different font
24+
25+
Under the hood the `logo` component uses the [`laminas/laminas-text`](https://github.com/laminas/laminas-text) package which renders text using fonts called "figlets".
26+
27+
By default Laravel Zero uses the `big.flf` FIGlet file by Glenn Chappell. Additional FIGlet files can be downloaded from [figlet.org](http://www.figlet.org/fontdb.cgi) or created using FIGlet editing software.
28+
29+
Once a font has been downloaded, the `logo.font` value can be set in the config to provide the full path to the FIGlet file.
30+
31+
```diff
32+
// config/logo.php
33+
- 'font' => \LaravelZero\Framework\Components\Logo\FigletString::DEFAULT_FONT,
34+
+ 'font' => resources_path('fonts/doom.flf'),
35+
```
36+
37+
For more details, check out the [Laminas docs](https://docs.laminas.dev/laminas-text/figlet) on FIGlets.

0 commit comments

Comments
 (0)