安装¶

安装 Composer¶

CakePHP 使用 Composer，一个依赖管理工具，作为官方支持的安装方法。

• 在 Linux 和 macOS 上安装 Composer

  1. 运行安装脚本，如 Composer 官方文档 中所述，并按照说明安装 Composer。

  2. 执行以下命令将 composer.phar 移动到您的路径中的目录

     mv composer.phar /usr/local/bin/composer
     

• 在 Windows 上安装 Composer

  对于 Windows 系统，您可以 此处 下载 Composer 的 Windows 安装程序。Composer 的 Windows 安装程序的进一步说明可以在 README 中找到 此处。

创建 CakePHP 项目¶

您可以使用 composer 的 create-project 命令创建一个新的 CakePHP 应用程序

composer create-project --prefer-dist cakephp/app:~5.0 my_app_name

一旦 Composer 完成下载应用程序骨架和核心 CakePHP 库，您应该通过 Composer 安装了一个功能正常的 CakePHP 应用程序。请务必将 composer.json 和 composer.lock 文件与您的其余源代码一起保存。

您现在可以访问安装 CakePHP 应用程序的路径，并查看默认主页。要更改此页面的内容，请编辑 templates/Pages/home.php。

虽然 composer 是推荐的安装方法，但 Github 上提供了预安装的下载文件。这些下载文件包含应用程序骨架以及所有已安装的供应商包。此外，它还包括 composer.phar，因此您拥有进一步使用所需的一切。

保持 CakePHP 最新更改¶

默认情况下，这是您的应用程序 composer.json 的样子

"require": {
    "cakephp/cakephp": "5.0.*"
}

每次运行 php composer.phar update 时，您将收到此次要版本的补丁版本。您可以将其更改为 ^5.0 以接收 5.x 分支的最新稳定次要版本。

使用 DDEV 安装¶

另一种快速安装 CakePHP 的方法是通过 DDEV。它是一个用于启动本地 Web 开发环境的开源工具。

如果您想配置一个新项目，您只需要

mkdir my-cakephp-app
cd my-cakephp-app
ddev config --project-type=cakephp --docroot=webroot
ddev composer create --prefer-dist cakephp/app:~5.0
ddev launch

如果您有一个现有项目

git clone <your-cakephp-repo>
cd <your-cakephp-project>
ddev config --project-type=cakephp --docroot=webroot
ddev composer install
ddev launch

有关如何安装/更新 DDEV 的详细信息，请查看 DDEV 文档。

Apache¶

虽然 CakePHP 是为开箱即用地与 mod_rewrite 协同工作而构建的（通常情况下确实如此），但我们注意到一些用户在让一切在其系统上完美运行方面遇到了困难。

以下是一些可能让它正常运行的尝试方法。首先查看您的 httpd.conf。（确保您正在编辑系统 httpd.conf，而不是用户或站点特定的 httpd.conf。）

这些文件在不同的发行版和 Apache 版本之间可能有所不同。您也可以查看 https://cwiki.apache.org/confluence/display/httpd/DistrosDefaultLayout 以获取更多信息。

1. 确保允许 .htaccess 覆盖，并且 AllowOverride 针对正确的 DocumentRoot 设置为 All。您应该看到类似以下内容

   # Each directory to which Apache has access can be configured with respect
   # to which services and features are allowed and/or disabled in that
   # directory (and its subdirectories).
   #
   # First, we configure the "default" to be a very restrictive set of
   # features.
   <Directory />
       Options FollowSymLinks
       AllowOverride All
   #    Order deny,allow
   #    Deny from all
   </Directory>
   

2. 确保您正确加载了 mod_rewrite。您应该看到类似以下内容

   LoadModule rewrite_module libexec/apache2/mod_rewrite.so
   

   在许多系统中，这些默认情况下会被注释掉，因此您可能只需要删除开头的 # 符号即可。

   在进行更改后，重新启动 Apache 以确保设置生效。

   验证您的 .htaccess 文件是否确实位于正确的目录中。一些操作系统将以“.”开头的文件视为隐藏文件，因此不会复制它们。

3. 确保您的 CakePHP 副本来自该网站的下载部分或我们的 Git 存储库，并且已正确解压缩，方法是检查是否存在 .htaccess 文件。

   CakePHP 应用程序目录（将由 bake 复制到应用程序的顶层目录）

   <IfModule mod_rewrite.c>
      RewriteEngine on
      RewriteRule    ^$    webroot/    [L]
      RewriteRule    (.*) webroot/$1    [L]
   </IfModule>
   

   CakePHP webroot 目录（将由 bake 复制到应用程序的 Web 根目录）

   <IfModule mod_rewrite.c>
       RewriteEngine On
       RewriteCond %{REQUEST_FILENAME} !-f
       RewriteRule ^ index.php [L]
   </IfModule>
   

   如果您的 CakePHP 网站在使用 mod_rewrite 时仍然存在问题，您可能需要尝试修改虚拟主机的设置。在 Ubuntu 上，编辑文件 /etc/apache2/sites-available/default（位置取决于发行版）。在此文件中，确保 AllowOverride None 更改为 AllowOverride All，以便您拥有

   <Directory />
       Options FollowSymLinks
       AllowOverride All
   </Directory>
   <Directory /var/www>
       Options FollowSymLinks
       AllowOverride All
       Order Allow,Deny
       Allow from all
   </Directory>
   

   在 macOS 上，另一种解决方案是使用工具 virtualhostx 创建指向您文件夹的虚拟主机。

   对于许多托管服务（GoDaddy、1and1），您的 Web 服务器是从已经使用 mod_rewrite 的用户目录提供的。如果您将 CakePHP 安装到用户目录（http://example.com/~username/cakephp/）或任何其他已经使用 mod_rewrite 的 URL 结构中，您需要将 RewriteBase 语句添加到 CakePHP 使用的 .htaccess 文件（.htaccess、webroot/.htaccess）。

   这可以添加到与 RewriteEngine 指令相同的节中，因此，例如，您的 webroot .htaccess 文件将如下所示

   <IfModule mod_rewrite.c>
       RewriteEngine On
       RewriteBase /path/to/app
       RewriteCond %{REQUEST_FILENAME} !-f
       RewriteRule ^ index.php [L]
   </IfModule>
   

   这些更改的详细信息将取决于您的设置，并且可能包括与 CakePHP 无关的额外内容。有关更多信息，请参阅 Apache 的在线文档。

4. （可选）为了改进生产环境，您应该阻止 CakePHP 解析无效的资产。将您的 webroot .htaccess 修改为类似以下内容

   <IfModule mod_rewrite.c>
       RewriteEngine On
       RewriteBase /path/to/app/
       RewriteCond %{REQUEST_FILENAME} !-f
       RewriteCond %{REQUEST_URI} !^/(webroot/)?(img|css|js)/(.*)$
       RewriteRule ^ index.php [L]
   </IfModule>
   

   以上操作将阻止错误的资产发送到 index.php，而是显示您的 Web 服务器的 404 页面。

   此外，您可以创建一个匹配的 HTML 404 页面，或通过添加 ErrorDocument 指令使用默认的内置 CakePHP 404

   ErrorDocument 404 /404-not-found
   

nginx¶

nginx 不像 Apache 那样使用 .htaccess 文件，因此有必要在站点可用配置中创建那些重写的 URL。这通常位于 /etc/nginx/sites-available/your_virtual_host_conf_file。根据您的设置，您将不得不修改它，但至少您需要以 FastCGI 实例运行 PHP。以下配置将请求重定向到 webroot/index.php

location / {
    try_files $uri $uri/ /index.php?$args;
}

服务器指令的示例如下

server {
    listen   80;
    listen   [::]:80;
    server_name www.example.com;
    return 301 http://example.com$request_uri;
}

server {
    listen   80;
    listen   [::]:80;
    server_name example.com;

    root   /var/www/example.com/public/webroot;
    index  index.php;

    access_log /var/www/example.com/log/access.log;
    error_log /var/www/example.com/log/error.log;

    location / {
        try_files $uri $uri/ /index.php?$args;
    }

    location ~ \.php$ {
        try_files $uri =404;
        include fastcgi_params;
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        fastcgi_intercept_errors on;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
}

NGINX Unit¶

NGINX Unit 在运行时是动态可配置的；以下配置依赖于 webroot/index.php，如果存在，还通过 cakephp_direct 提供其他 .php 脚本

{
    "listeners": {
        "*:80": {
            "pass": "routes/cakephp"
        }
    },

    "routes": {
        "cakephp": [
            {
                "match": {
                    "uri": [
                        "*.php",
                        "*.php/*"
                    ]
                },

                "action": {
                    "pass": "applications/cakephp_direct"
                }
            },
            {
                "action": {
                    "share": "/path/to/cakephp/webroot/",
                    "fallback": {
                        "pass": "applications/cakephp_index"
                    }
                }
            }
        ]
    },

    "applications": {
        "cakephp_direct": {
            "type": "php",
            "root": "/path/to/cakephp/webroot/",
            "user": "www-data"
        },

        "cakephp_index": {
            "type": "php",
            "root": "/path/to/cakephp/webroot/",
            "user": "www-data",
            "script": "index.php"
        }
    }
}

要启用此配置（假设它保存为 cakephp.json）

# curl -X PUT --data-binary @cakephp.json --unix-socket \
       /path/to/control.unit.sock https://127.0.0.1/config

IIS7（Windows 主机）¶

IIS7 本身不支持 .htaccess 文件。虽然有一些插件可以添加此支持，但您也可以将 htaccess 规则导入 IIS 以使用 CakePHP 的本机重写。为此，请按照以下步骤操作

1. 使用 Microsoft 的 Web 平台安装程序 安装 URL 重写模块 2.0 或直接下载它（32 位 / 64 位）。

2. 在您的 CakePHP 根文件夹中创建一个名为 web.config 的新文件。

3. 使用记事本或任何 XML 安全的编辑器，将以下代码复制到您新的 web.config 文件中

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <rewrite>
            <rules>
                <rule name="Exclude direct access to webroot/*"
                  stopProcessing="true">
                    <match url="^webroot/(.*)$" ignoreCase="false" />
                    <action type="None" />
                </rule>
                <rule name="Rewrite routed access to assets(img, css, files, js, favicon)"
                  stopProcessing="true">
                    <match url="^(font|img|css|files|js|favicon.ico)(.*)$" />
                    <action type="Rewrite" url="webroot/{R:1}{R:2}"
                      appendQueryString="false" />
                </rule>
                <rule name="Rewrite requested file/folder to index.php"
                  stopProcessing="true">
                    <match url="^(.*)$" ignoreCase="false" />
                    <action type="Rewrite" url="index.php"
                      appendQueryString="true" />
                </rule>
            </rules>
        </rewrite>
    </system.webServer>
</configuration>

一旦使用正确的 IIS 友好重写规则创建了 web.config 文件，CakePHP 的链接、CSS、JavaScript 和重定向应该可以正常工作。

Lighttpd¶

Lighttpd 不像 Apache 那样使用 .htaccess 文件，因此有必要在 conf/lighttpd.conf 中添加 url.rewrite-once 配置。确保您的 lighthttpd 配置中存在以下内容

server.modules += (
    "mod_alias",
    "mod_cgi",
    "mod_rewrite"
)

# Directory Alias
alias.url       = ( "/TestCake" => "C:/Users/Nicola/Documents/TestCake" )

# CGI Php
cgi.assign      = ( ".php" => "c:/php/php-cgi.exe" )

# Rewrite Cake Php (on /TestCake path)
url.rewrite-once = (
    "^/TestCake/(css|files|img|js|stats)/(.*)$" => "/TestCake/webroot/$1/$2",
    "^/TestCake/(.*)$" => "/TestCake/webroot/index.php/$1"
)

以上行包括 PHP CGI 配置和路径为 /TestCake 的应用程序示例配置。

我无法使用 URL 重写¶

如果您不想或无法在服务器上运行 mod_rewrite（或某些其他兼容模块），您将需要使用 CakePHP 内置的漂亮 URL。在 config/app.php 中，取消注释看起来像这样的行

'App' => [
    // ...
    // 'baseUrl' => env('SCRIPT_NAME'),
]

还要删除这些 .htaccess 文件

/.htaccess
webroot/.htaccess

这将使您的 URL 看起来像 www.example.com/index.php/controllername/actionname/param 而不是 www.example.com/controllername/actionname/param。