[TOC]
# 概况
Phalcon Box使用[Vagrant Cloud](https://atlas.hashicorp.com/phalconphp/boxes/xenial64/)的默认**phalcon/xenial64** box 来兼容。如果您选择使用64位ISO，则可能需要更新BIOS以使用`AMD-V`，`Intel VT-x`或`VIA VT`进行虚拟化。
第一次使用`vagrant up`配置新环境时，由于必须首先将box（`phalconphp/xenial64`）下载到本地计算机，因此该过程将花费更长的时间。任何后续的环境条款都会快得多。
## 要求
* 操作系统： Windows, Linux, or macOS
* [Virtualbox](https://www.virtualbox.org/wiki/Downloads) >= 5.1 (如果使用 Virtualbox box)
* [VMware Fusion](http://www.vmware.com/products/fusion) (或者 Workstation - 如果使用 VMware box)
* [Vagrant](https://www.vagrantup.com/downloads.html) >= 1.9.8
## 预装软件
* Ansible
* Beanstalkd
* Blackfire
* Composer
* Git
* goreplace
* Mailhog
* Memcached
* MongoDB
* MySQL
* Nginx
* Ngrok
* Node.js (with Yarn, Bower, Grunt, and Gulp)
* PHIVE
* PHP 7.1
* PHPMD
* PHP_CodeSniffer
* Phalcon
* Phing
* PostgreSQL
* Redis
* Sqlite3
* Ubuntu 16.04
* Zephir
## 安装
### 安装 Vagrant Box
在启动Phalcon Box环境之前，您必须安装VirtualBox，VMWare以及Vagrant。所有这些软件包都为所有流行的操作系统提供易于使用的可视化安装程序。
安装VirtualBox/VMWare和Vagrant后，应使用终端中的以下命令将`phalconphp/xenial64` box 加到Vagrant安装中。下载此box将需要几分钟，具体取决于您的网络连接速度：
```bash
vagrant box add phalconphp/xenial64
```
如果此命令失败，请确保您的Vagrant安装是最新的。
>[warning] 要使用`VMware`，您需要同时购买`VMware Fusion/Workstation`和[VMware Vagrant](https://www.vagrantup.com/vmware)插件。虽然它不是免费的，但VMware可以提供更快的共享文件夹功能。
### 安装 Phalcon Box
您只需clone存储库即可安装`Phalcon Box`。考虑将存储库克隆到主目录中的工作区文件夹中，因为Phalcon Box框将作为所有Phalcon项目的主机：
```bash
cd ~
git clone https://github.com/phalcon/box.git workspace
```
`master`分支将始终包含Phalcon Box的最新稳定版本。如果您想查看当前正在开发的旧版本或更新版本，请切换到相关的branch/tag。
(https://github.com/phalcon/box/releases):
您可以在[Github发布页面](https://github.com/phalcon/box/releases)上找到最新的稳定版本：
```bash
# Clone the desired release...
git checkout v2.4.0
```
克隆Phalcon Box存储库后，从Phalcon Box根目录运行install命令以创建`settings.yml`配置文件。`settings.yml`文件将放在Phalcon Box目录中：
```bash
# macOS || Linux
./install
```
```cmd
rem Windows
install.bat
```
现在您已准备好配置虚拟机，运行：
```bash
vagrant up
```
<a name='installation-configuration'></a>
## 配置
### 设置您的提供平台
`settings.yml`文件中的提供程序密钥指示应使用哪个Vagrant提供程序：`virtualbox`，`vmware_fusion`或`vmware_workstation`。您可以将其设置为您喜欢的提供平台：
```yaml
provider: virtualbox
```
### 内存和 CPU
默认情况下，此设置使用2GB RAM。您可以在`settings.yml`中更改此设置，只需运行`vagrant reload`：
```yaml
memory: 4096
```
如果您愿意，也可以使用多个cup，只需在同一文件中更改此行：
```yaml
cpus: 4
```
### 共享文件夹
`settings.yml`文件的`folders`属性列出了您希望与Phalcon Box环境共享的所有文件夹。当这些文件夹中的文件发生更改时，它们将在本地计算机和Phalcon Box环境之间保持同步。您可以根据需要配置任意数量的共享文件夹：
```yaml
folders:
- map: ~/workspace
to: /home/vagrant/workspace
```
要启用[NFS](https://www.vagrantup.com/docs/synced-folders/nfs.html)，只需在同步文件夹配置中添加一个简单标志：
```yaml
folders:
- map: ~/workspace
to: /home/vagrant/workspace
type: "nfs"
```
You may also pass any options supported by Vagrant's [Synced Folders](https://www.vagrantup.com/docs/synced-folders/basic_usage.html) by listing them under the `options` key:
您也可以通过在选项键下列出Vagrant[同步文件夹](https://www.vagrantup.com/docs/synced-folders/basic_usage.html)支持的任何`options`：
```yaml
folders:
- map: ~/workspace
to: /home/vagrant/workspace
type: "nfs"
options:
rsync__args: ["--verbose", "--archive", "--delete", "-zz"]
rsync__exclude: ["node_modules"]
```
>[danger] macOS用户可能需要安装`vagrant-bindfs`插件来修复共享文件夹（NFS）权限问题：
```bash
vagrant plugin install vagrant-bindfs
```
### Nginx站点
`sites`属性允许您轻松地将“域”映射到Phalcon Box环境中的文件夹。`settings.yml`文件中包含示例站点配置。您可以根据需要向Phalcon Box环境添加任意数量的站点。Phalcon Box可作为您正在处理的每个Phalcon项目的便捷虚拟化环境：
```yaml
sites:
- map: phalcon.local
to: /home/vagrant/workspace/phalcon/public
```
您可以使用`type`参数指定站点的Nginx配置类型。例如：
```yaml
sites:
- map: landing.local
to: /home/vagrant/workspace/landing/public
type: spa
```
默认类型是`phalcon`。如果不允许或不提供所需类型，`phalcon`将用作后备。
可用类型：
* `phalcon`
* `slayer`
* `phanbook`
* `proxy`
* `spa`
* `silverstripe`
* `symfony2`
* `statamic`
* `laravel`
* `zend`
通过打开[新功能请求](https://github.com/phalcon/box/issues/new)，随意建新类型的Nginx配置。
>[warning] 如果在配置Phalcon Box后更改`sites`属性，则必须重新运行`vagrant reload --provision`以更新虚拟机上的Nginx配置。
#### 自定义Nginx配置
您也可以创建自己的类型。为此，请将`provisioning/templates/nginx`文件夹中的任何模板作为基础并进行必要的更改。您需要将此文件放在同一文件夹中。之后，您将能够使用自己的自定义类型：
```yaml
sites:
- map: my-site.local
to: /home/vagrant/workspace/my-site/public
# provisioning/templates/nginx/phalcon-advanced.conf.j2
type: phalcon-advanced
```
您需要自定义*全局*Nginx配置吗？是的，这是可能的。Fox示例，让我们创建autoindex配置。
文件 `/home/user/nginx.d/00-autoindex.conf`：
```nginx
# Processes requests ending with the slash character (‘/’) and produces a directory listing
autoindex on;
```
将所需的设置添加到您的文件，然后将其添加到 `copy`部分：
```yaml
copy:
- from: /home/user/nginx.d/00-autoindex.conf
to: /etc/nginx/conf.d/
```
#### 配置`hosts`文件
您必须将Nginx站点的“域”添加到计算机上的hosts文件中。hosts文件会将Phalcon站点的请求重定向到Phalcon Box计算机。在Mac和Linux上，此文件位于`/etc/hosts`。在Windows上，它位于`C:\Windows\System32\drivers\etc\hosts`。您添加到此文件的行将如下所示：
192.168.50.4 phalcon.local
确保列出的IP地址是`settings.yml`文件中设置的IP地址。将域添加到`hosts`文件并启动Vagrant框后，您将可以通过Web浏览器访问该站点：
http://phalcon.local
>[danger] 要启用将新站点添加到`hosts`文件，请自动使用`vagrant-hostsupdater`插件：
```bash
vagrant plugin install vagrant-hostsupdater
```
### 安装其他软件包
我们尽最大努力为Phalcon Box提供所有必要的程序和库。然而，应该理解，典型的用户不需要可以安装的所有可能的包。Phalcon Box必须具有合理的尺寸，以便即使是那些在互联网频道带宽方面遇到困难的人也可以使用它。
出于这些考虑，我们允许用户指定每个配置所需的自定义包。要安装必要的软件包，请在`apt`部分添加其名称：
```yaml
# Provisioning features
provision:
# do full system update for each full provisoning
update: true
# Install wkhtmltopdf and libffi-dev packages
apt:
- wkhtmltopdf
- libffi-dev
```
### 运行Phalcon Box
根据自己的喜好编辑`settings.yml`后，从Phalcon Box目录运行`vagrant up`命令（例如`$HOME/workspace`）。Vagrant将启动虚拟机并自动配置您的共享文件夹和Nginx站点。
要销毁机器，可以使用`vagrant destroy --force`命令。
## 日常使用
### 全局访问Phalcon Box
Phalcon Box installation:
有时你可能想要从文件系统的任何地方`vagrant up`你的Phalcon Box机器。您可以在Mac或Linux系统上通过向Bash配置文件添加[Bash function](http://tldp.org/HOWTO/Bash-Prog-Intro-HOWTO-8.html)来执行此操作。在Windows上，您可以通过向`PATH`添加“批处理”文件来完成此操作。这些脚本允许您从系统的任何位置运行任何Vagrant命令，并自动将该命令指向Phalcon Box安装：
#### Mac || Linux
```bash
function box()
{
( cd $HOME/workspace && vagrant $* )
}
```
>[warning] 确保将函数中的`$HOME/workspace`路径调整到实际Phalcon Box安装的位置。安装该功能后，您可以从系统的任何位置运行`box up`或`box ssh`等命令。
#### Windows
使用以下内容在计算机的任何位置创建`box.bat`批处理文件：
```cmd
@echo off
set cwd=%cd%
set box=C:\workspace
cd /d %box% && vagrant %*
cd /d %cwd%
set cwd=
set box=
```
>[warning] 确保将脚本中的示例`C:\workspace`路径调整为Phalcon Box安装的实际位置。创建文件后，将文件位置添加到`PATH`。然后，您可以从系统的任何位置运行诸如`box up`或`box ssh`之类的命令。
### 通过SSH连接
您可以通过从Phalcon Box目录发出`vagrant ssh` 终端命令来SSH命令进入到您的虚拟机。
但是，由于您可能需要经常SSH到Phalcon Box机器，请考虑将上述“功能”添加到主机以快速SSH到Phalcon Box。
### 连接数据库
要从主机的数据库客户端连接到MySQL，Postgres或MongoDB数据库，您应该连接到`127.0.0.1`和端口`33060`（MySQL），`54320`（Postgres）或`27017`（MongoDB）。数据库的用户名和密码是`phalcon` / `secret`。
>[danger] 从主机连接到数据库时，只应使用这些非标准端口。由于Phalcon在虚拟机中运行，因此您将使用Phalcon数据库配置文件中的默认330和``端口。
要从Phalcon Box类型访问交互式数据库控制台，请执行以下操作：
* **Postgres:** `psql -U phalcon -h localhost` (密码 `secret`)
* **MySQL:** `mysql` (CLI工具不需密码)
* **MongoDB:** `mongo` (CLI工具不需密码)
### 添加其他站点
配置并运行Phalcon Box环境后，您可能需要为应用程序添加其他Nginx站点。您可以在单个Phalcon Box环境中运行任意数量的Phalcon项目。要添加其他站点，只需将站点添加到`settings.yml`文件：
```yaml
sites:
- map: phalcon.local
to: /home/vagrant/workspace/phalcon/public
- map: pdffiller.local
to: /home/vagrant/workspace/pdffiller/public
- map: blog.local
to: /home/vagrant/workspace/blog/public
```
如果Vagrant没有自动管理您的“hosts”文件，您可能还需要将新站点添加到该文件：
192.168.50.4 phalcon.local
192.168.50.4 pdffiller.local
192.168.50.4 blog.local
>[danger] 要启用将新站点添加到`hosts`文件，请自动使用`vagrant-hostsupdater`插件：
```bash
vagrant plugin install vagrant-hostsupdater
```
添加站点后，从Phalcon Box目录运行`vagrant reload --provision`命令。
### 环境变量
#### 全局变量
您可以轻松注册全局环境变量。只需将变量及其值添加到`variables`部分：
```yaml
variables:
- key: TEST_DB_MYSQL_USER
value: phalcon
- key: TEST_DB_MYSQL_PASSWD
value: secret
- key: TEST_DB_MYSQL_DSN
value: "mysql:host=127.0.0.1;dbname=phalcon_test"
```
这样，您就可以在应用程序或脚本中使用这些变量。例如，以这种方式配置[Codeception](http://codeception.com)：
```yaml
# File codeception.yml
params:
# Get params from environment
- env
```
您可以按如下方式配置Unit套件：
```yaml
# File tests/unit.suite.yml
class_name: UnitTester
modules:
enabled:
- Db
config
Db:
dsn: %TEST_DB_MYSQL_DSN%
user: %TEST_DB_MYSQL_USER%
password: %TEST_DB_MYSQL_PASSWD%
populate: true
cleanup: false
dump: tests/_data/schemas/mysql/mysql.dump.sql
```
#### Site变量
Site 变量是指如何在Phalcon Box中轻松将`fastcgi_param`值添加到站点主机配置中。例如，我们可以添加`development`这个值给`APP_ENV`变量：
```yaml
sites:
- map: phalconbox.local
to: /var/www/phalconbox/public
variables:
- key: APP_ENV
value: development
# Yet another example
- key: AMQP_DEBUG
value: true
```
### 端口
默认情况下，以下端口将转发到Phalcon Box环境：
| 转发港口 | Phalcon Box | 主机系统 |
| -------------- |:-----------:|:-----------:|
| **SSH** | `22` | `2222` |
| **HTTP** | `80` | `8000` |
| **HTTPS** | `443` | `44300` |
| **MySQL** | `3306` | `33060` |
| **Postgres** | `5432` | `54320` |
| **MailHog** | `8025` | `8025` |
#### 转发其他端口
如果您愿意，您可以将其他端口转发到Phalcon Box，并指定其协议：
```yaml
ports:
- send: 63790
to: 6379
- send: 50000
to: 5000
- send: 7777
to: 777
protocol: udp
```
### 分享您的环境
有时您可能希望与同事或客户分享您目前正在处理的内容。Vagrant有一种内置的方式`vagrant share`来支持;但是，如果您在`settings.yml`文件中配置了多个站点，则无法使用此功能。
为解决此问题，Phalcon Box包含自己的`share`命令。首先，通过`vagrant ssh` SSH到Phalcon Box机器并运行`share <your-site-here>`，例如：`share blog.local`。这将从`settings.yml`配置文件共享您的站点。当然，您可以将任何其他配置的站点替换为`blog.local`：
```bash
share blog.local
```
运行该命令后，您将看到一个[Ngrok](https://ngrok.com)屏幕，其中包含活动日志和共享站点的可公开访问的URL。如果要指定自定义区域，子域或其他Ngrok运行时选项，可以将它们添加到`share`命令：
```bash
share blog.local -region=eu -subdomain=phalcongelist
```
>[danger] Vagrant本质上是不安全的，您在运行`share`命令时将虚拟机暴露给互联网。
### 网络接口
`settings.yml`的`networks`属性为Phalcon Box环境配置网络接口。您可以根据需要配置任意数量的接口：
```yaml
networks:
- type: "private_network"
ip: "192.168.50.99"
```
要启用[桥接](https://www.vagrantup.com/docs/networking/public_network.html)接口，请配置`网桥`设置并将网络类型更改为`public_network`：
```yaml
networks:
- type: "private_network"
ip: "192.168.50.99"
bridge: "en1: Wi-Fi (AirPort)"
```
要启用[DHCP](https://www.vagrantup.com/docs/networking/public_network.html)，只需从此配置中删除`ip`选项：
```yaml
networks:
- type: "private_network"
bridge: "en1: Wi-Fi (AirPort)"
```
### 更新Phalcon Box
您可以通过两个简单的步骤更新Phalcon Box。
1. 首先，您需要使用`vagrant box update`命令更新Vagrant框：
```bash
vagrant box update
```
2. 接下来，您需要更新Phalcon Box源代码。如果你克隆了存储库，你可以简单地
```bash
git pull origin master
```
在您最初克隆存储库的位置。
新版Phalcon Box将包含更新或修改的配置文件：
* `settings.yml`
* `.bash_aliases`
* `after_provision.sh`
运行命令`./install`（或`install.bat`）时，Phalcon Box会在根目录中创建这些文件。但是，如果文件已存在，则不会覆盖它们。
我们建议您始终对这些文件进行备份，并将其从项目中删除，以便可以复制新更新的文件。然后，您可以将自己的文件与phalcon框进行比较，以应用您的个性化更改并利用更新提供的新功能。
### 提供平台特定设置
#### VirtualBox
默认情况下，Phalcon Box将`natdnshostresolver`设置配置为`on`。这允许Phalcon Box使用您的主机操作系统的DNS设置。如果要覆盖此行为，请将以下行添加到`settings.ym`l文件中：
```yaml
natdnshostresolver: off
```
### Mail捕捉器
默认情况下，Phalcon Box会将所有PHP电子邮件重定向到[MailHog](https://github.com/mailhog/MailHog) （而不是将它们发送到外部世界）。您可以在`http://localhost:8025/`（或您在`settings.yml`中配置的任何域）访问MailHog UI。
## 故障排除
**问题：**
> An error occurred in the underlying SSH library that Vagrant uses. The error message is shown below. In many cases, errors from this library are caused by ssh-agent issues. Try disabling your SSH agent or removing some keys and try again. If the problem persists, please report a bug to the net-ssh project. timeout during server version negotiating
**解决：**
```bash
vagrant plugin install vagrant-vbguest
```
**问题：**
> Vagrant was unable to mount VirtualBox shared folders. This is usually because the filesystem "vboxsf" is not available. This filesystem is made available via the VirtualBox Guest Additions and kernel module. Please verify that these guest additions are properly installed in the guest. This is not a bug in Vagrant and is usually caused by a faulty Vagrant box. For context, the command attempted was:
>
> mount -t vboxsf -o uid=900,gid=900 vagrant /vagrant
**解决：**
```bash
vagrant plugin install vagrant-vbguest
```
**问题：**
> There was an error while executing `VBoxManage`, a CLI used by Vagrant for controlling VirtualBox. The command and stderr is shown below.
>
> Command: `["startvm", "9d2b95e1-0fdd-40f4-ad65-4b56eb4315f8", "--type", "headless"]`
>
> Stderr: VBoxManage.exe: error: VT-x is not available (VERR_VMX_NO_VMX) VBoxManage.exe: error: Details: code E_FAIL (0x80004005), component ConsoleWrap, interface IConsole
**解决：**
您需要更新BIOS以使用`Intel VT-x`启用[虚拟化](https://en.wikipedia.org/wiki/X86_virtualization)。
- 常规
- Welcome
- 贡献
- 生成回溯
- 测试重现
- 单元测试
- 入门
- 安装
- Web服务器设置
- WAMP
- XAMPP
- 教程
- 基础教程
- 教程：创建一个简单的REST API
- 教程：Vökuró
- 提升性能
- 教程：INVO
- 开发环境
- Phalcon Compose (Docker)
- Nanobox
- Phalcon Box (Vagrant)
- 开发工具
- Phalcon开发者工具的安装
- Phalcon开发者工具的使用
- 调试应用程序
- 核心
- MVC应用
- 微应用
- 创建命令行（CLI）应用程序
- 依赖注入与服务定位
- MVC架构
- 服务
- 使用缓存提高性能
- 读取配置
- 上下文转义
- 类加载器
- 使用命名空间
- 日志
- 队列
- 数据库
- 数据库抽象层
- Phalcon查询语言（PHQL）
- ODM（对象文档映射器）
- 使用模型
- 模型行为
- ORM缓存
- 模型事件
- 模型元数据
- 模型关系
- 模型事务
- 验证模型
- 数据库迁移
- 分页
- 前端
- Assets管理
- 闪存消息
- 表单
- 图像
- 视图助手（标签）
- 使用视图
- Volt：模板引擎
- 业务逻辑
- 访问控制列表（ACL）
- 注解解析器
- 控制器
- 调度控制器
- 事件管理器
- 过滤与清理
- 路由
- 在session中存储数据
- 生成URL和路径
- 验证
- HTTP
- Cookies管理
- 请求环境
- 返回响应
- 安全
- 加密/解密
- 安全
- 国际化
- 国际化
- 多语言支持