# PHPSandbox CLI

PHPSandbox CLI is a fully open source command line tool for PHPSandbox. It allows you to interact with PHPSandbox from the command line

# Requirements

Before installing PHPSandbox, ensure that your development environment meets the following requirements

  • Composer => 1.0
  • PHP => 7.4

once you have these requirements met, you are good to go. Go ahead and install the PHPSandbox CLI tool.

# Installation

The PHPSandbox CLI tool can be easily installed via composer. It should be installed as a global composer dependency so it would be available for all your projects. Running the command below would install the latest version on your computer.

composer global require phpsandbox/cli

Once the installation is successful, ensure that your global composer vendor bin folder is added to your system global path so that the system would find the phpsandbox cli executable. This directory exists in different locations based on your operating system; however, some common locations include:

  • macOS: $HOME/.composer/vendor/bin
  • Windows: %USERPROFILE%\AppData\Roaming\Composer\vendor\bin
  • GNU / Linux Distributions: $HOME/.config/composer/vendor/bin or $HOME/.composer/vendor/bin

You can also run composer global about to find the path to your global composer installation.

Once this is done, running the psb command should show you the CLI version and available commands like this

psb

You should see this if all goes well

# Project Requirement

To export your project , there are a few things the PHPSandbox CLI tool looks out for. These are requirements the project is expected to meet. They include

  • The project must be a composer project .
  • The project must have a valid composer.json file at it root directory.
  • The total size (excluding the vendor folder and node modules) should not exceed 10MB.

# Available Features

  • Importing a Notebook from PHPSandbox
  • Exporting a local project to PHPSandbox
  • Creating a config file for your local project

# Available Commands

# Login Command

The login command authenticates a user with the PHPSandbox CLI. Running the psb login command opens an access token retrieval link on your default browser where you would be shown your access token.

PHPSandbox access token

The access token is then used to complete the authentication process by pasting it in the prompt on the command-line/terminal

PHPSandbox authentication

The login command can take an optional token option . The token passed here would be used as the access token and the access token retrieval link would not be opened in the users browser.

PHPSandbox authenticate with token

TIP

Being authenticated is required to export your projects to phpsandbox.

psb login --token=mytoken

# Logout Command

The command logs out an authenticated user from the CLI. For a successful logout, you should see something like this

 psb logout

logout command

# Export command

The command exports the current working directory to create a notebook on phpsandbox. Authentication is required to use this command and you would be prompted to get authenticated first if you are not yet authenticated. The project being exported would first be validated to confirm that it meets the project requirement before it is compressed and exported. If the project is a git project, files specified in your gitignore would not be included in the files to be exported. If the project fails any of the validation, the export process is halted. After a sucessful export, you should see something like this

The provisioned notebook would be launched on the users default browser.

psb export

# Import command

The import command downloads a notebook from PHPSandbox to your local development environment. The command for this is

psb import notebook-id

By default, the import command would download the notebook in the current working directory but you can provide a path option to the command to specify where the downloaded notebook should be stored. Ensure that such is path is writable. psb import notebook-id --path=/path/to/download/directory All public notebooks can be imported by any user. Once the download is complete, all of the project dependencies as defined in the project composer.json file would be installed as well with all the logs being displayed on the command line.

# Config command

When exporting your project to PHPSandbox, one of the things it checks is if you have a phpsandbox.json file at the root directory os the project. This file would contain configuration options that tells PHPSandbox how to provision your notebook. To generate a phpsandbox.json config file for your project, run the config init command

psb config:init

This takes you through the various configuration options and adds a phpsandbox.json file to the base directory of your project.