DEV Community: Ken Ng

The right way to fix PHP-FPM 'primary script unknown' issue

Ken Ng — Sat, 09 Nov 2024 03:16:31 +0000

Introduction

Many online resources only outline potential causes and solutions for issues related to upgrading PHP versions, leaving users without a clear, step-by-step guide to resolve their problems. This tutorial aims to document the process of upgrading from PHP 8.2 to PHP 8.3 on Amazon Linux 2023 with Nginx, providing a comprehensive guide that can save developers from hours of frustration.

Objective

Objective: Upgrade from PHP 8.2 to PHP 8.3

Server Specs

OS: Amazon Linux 2023  
Server: NGINX 1.26.2

Problem Statement

After upgrading PHP, you may encounter errors in the Nginx error log, such as:

2024/11/09 01:54:40 [error] 3394#3394: *33 FastCGI sent in stderr: "Primary script unknown" while reading response header from upstream, client: 127.0.0.1, server: abc.com, request: "GET /my-api HTTP/1.1", upstream: "fastcgi://unix:/run/php-fpm/www.sock:", host: "abc.com"

This error typically indicates issues with the FastCGI configuration or permissions.

Potential Causes of the Issue

Incorrectly Configured Nginx `fastcgi_param` Directive

The fastcgi_param directive in your Nginx configuration may not be set correctly. However, since the application was functioning properly before the upgrade, this is likely not the primary cause.

location ~ \.php$ {
    fastcgi_pass    unix:/run/php-fpm/www.sock;
    fastcgi_param   SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include         /etc/nginx/fastcgi_params;
}

Incorrect User Permissions

Given that we just upgraded PHP and PHP-FPM, it's possible that the new PHP-FPM configuration is set to an incorrect user or group. This warrants further investigation.

Debugging Steps

To effectively troubleshoot the issue, follow these steps:

Step 1: Locate the Correct `php-fpm.ini` Using `systemctl`

To find the php-fpm.conf, use the following command:

systemctl status php-fpm

This will display output similar to:

ec2-user ~/public_html  01:20:48$ systemctl status php-fpm
● php-fpm.service - The PHP FastCGI Process Manager
     Loaded: loaded (/usr/lib/systemd/system/php-fpm.service; disabled; preset: disabled)
     Active: active (running) since Sat 2024-11-09 00:44:23 UTC; 1h 5min ago
   Main PID: 3374 (php-fpm)
     Status: "Processes active: 0, idle: 7, Requests: 1, slow: 0, Traffic: 0.00req/sec"
      Tasks: 8 (limit: 4659)
     Memory: 12.3M
        CPU: 304ms
     CGroup: /system.slice/php-fpm.service
             ├─3374 "php-fpm: master process (/etc/php-fpm.conf)"
             ├─3377 "php-fpm: pool www"
             ├─3378 "php-fpm: pool www"
             ├─3379 "php-fpm: pool www"
             ├─3380 "php-fpm: pool www"
             └─3381 "php-fpm: pool www"

From this output, note that it is using /etc/php-fpm.conf.

Step 2: Check the PHP-FPM User Configuration

Open the configuration file:

less /etc/php-fpm.conf

If there is no user setting configured, check for additional configurations in /etc/php-fpm.d/*.conf. Navigate to this directory:

cd /etc/php-fpm.d/
ls

Make a backup of www.conf before editing:

sudo cp www.conf www.conf.bk
sudo vim www.conf

If the file contains:

[www]
user = apache
group = apache

and you’re using NGINX, update user and group to match your NGINX user configuration, typically nginx for both.

After making changes, restart the PHP-FPM service:

systemctl restart php-fpm
systemctl status php-fpm

If everything is configured correctly, your website should be accessible again.

Step 3: Verify User Permissions

If the user and group are correct but issues persist, verify that the user has access to the specified web directory. This is a common issue since users like apache or nginx often lack interactive login capabilities.

To check permissions:

Backup your /etc/passwd file:

   cp /etc/passwd /etc/passwd.bk

Edit /etc/passwd:

   vim /etc/passwd

Change the shell for the user:

nginx:x:992:992:Nginx web server:/var/lib/nginx:/bin/bash

Now switch to the nginx user and check directory access:

su - nginx
cd /path/to/web/directory/

Best Practices

Always Backup Before Upgrading

Take a snapshot backup of your server before performing upgrades. This allows for quick restoration if issues arise during production changes.

Test Upgrades on a Staging Server

Whenever possible, perform upgrades on a staging server before applying them in production environments to mitigate risks.

Conclusion

This guide should help you troubleshoot and fix NGINX’s “Primary script unknown” error following a PHP upgrade, while covering best practices for secure and smooth upgrades.

Vuejs3 Template Refs inside v-for

Ken Ng — Sat, 06 May 2023 03:21:41 +0000

Here's a short tutorial on using Vue.js3 template refs inside v-for to call child component methods with the Composition API.

Assuming you want to invoke the reset function of each child component, you can accomplish this as follows:

App.vue

<script setup>
import { ref } from 'vue'
import Comp from './Comp.vue'
import Comp1 from './Comp1.vue'
const compRefs = ref([])

function onReset() {
  compRefs.value.forEach(comp => comp.onReset())
}
</script>

<template>
  <div v-for="n of [0, 1, 2]">
    <template v-if="0 === n % 2">
      loop {{n}}: <Comp ref="compRefs"></Comp>
    </template>
    <template v-if="1 === n % 2">
      loop {{n}}:<Comp1 ref="compRefs"></Comp1>
    </template>
  </div>
  <button @click="onReset">
    Reset
  </button>
</template>

Comp.vue

<script setup>
import { ref } from 'vue'
const msg = ref('')

function onReset() {
  msg.value = 'Reset is activated'
}

defineExpose({ onReset })
</script>

<template>
  <div>
   Child COM {{ msg ? ':' + msg : '' }}
  </div>
</template>

Comp1.vue

<script setup>
import { ref } from 'vue'
const msg = ref('')

function onReset() {
  msg.value = 'Reset is activated'
}

defineExpose({ onReset })
</script>

<template>
  <div>
    Child COM1 {{ msg ? ':' + msg : '' }}
  </div>
</template>

Please note that the function you want to invoke must be exposed and the template ref should be placed on the child component, rather than on the div where the v-for directive is specified. This is because we need to access the function of the child component.

You can checkout the code on this playground.

That's all, Enjoy!

Migrating from ASP.net to PHP Laravel

Ken Ng — Mon, 06 Mar 2023 12:13:34 +0000

Recently, we had a project to migrate from ASP.NET to Laravel. During the process, we found that the information on the internet was scattered and disorganized. At times, we had to check the Laravel framework source code to truly understand what had gone wrong. Therefore, this post serves to record the issues we encountered during the migration and how we solved them.

As we were only migrating the backend language while keeping the SQL Server database, we did not want to go too deep into ASP.NET. Consequently, there is a high chance that we may have misinterpreted the ASP.NET information presented below. Please let us know if we have.

First off, there are differences in the SQL Server database schema compared to the conventional MySQL database used by Laravel.

Take the user table as an example. The default AspNetUsers table uses the column "Id" (than "id") as its primary key, which is stored as a 128-bit GUID string by default. To model the AspNetUsers table, we had to set the primary key and cast its type to a string in the user model, like so:

Models\User.php

class User extends Authenticatable
{
    public $table = "<your-schema>.AspNetUsers";
    protected $primaryKey = 'Id';
    protected $keyType = 'string';

Without specifying the $primaryKey, you will encounter an error like the one below, as Laravel tries to inject the instance model using id.

Missing required parameter for [URI: products/{record}/edit] [Missing parameter: record].

If without specifying the the $keyType to string, you will encounter an error like the one below.

SQLSTATE[22018]: [Microsoft][ODBC Driver 18 for SQL Server][SQL Server]Conversion failed when converting the nvarchar value 'xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' to data type int. (Connection: sqlsrv, SQL: select top 1 * from [<your-schema>].[AspNetUsers] where [Id] = 5637154)

We are using SQL Server via a Docker image. To access the SQL Server, we have to set the .env and config/database.php files.

DB_CONNECTION=sqlsrv
DB_HOST=127.0.0.1
DB_PORT=1433
DB_DATABASE=XXX
DB_USERNAME=XXX
DB_PASSWORD=XXX

config/database.php:

'trust_server_certificate' => env('DB_TRUST_SERVER_CERTIFICATE', 'true'),

To test if the above settings are correct, you can try running tinker and pulling user data from the database. If that works, you are good to proceed with your next step.

This is a rather short blog, but we hope that it is useful for anyone who is looking to migrate from ASP.NET to Laravel.

Dart Good Practice: separate Model, UI view and controller logic

Ken Ng — Fri, 10 Jun 2022 09:02:53 +0000

MVC architecture is a design pattern to separate the application into three parts, namely: the model part, the view and the controller.

In day to day code review, it is noticed that developers tend to directly use unprocessed model data into the UI view. Not only that this will create a lot of extra if-else null checking logic in the final compiled code, it make the code looks very verbose.

See the example with pseudocode below:

Not Recommended:

   Text(_ctrl.sales?.amount ?? ''),
   Text(_ctrl.sales?.quantity ?? ''),
   Text(_ctrl.sales?.month ?? ''),

Good
controller.dart

late SaleModel sales;

onFetch() async {
  var res = await fetch('https://abc.com/sales');
  if (null != res.data && null != res.data.sales) {
    sales = SaleModel.fromJson(res.data.sales);
  } else {
    // declare a named constructor which return SaleModel with blank string
    sales = SaleModel.blank();
  }
}

UI view

   Text(_ctrl.sales.amount),
   Text(_ctrl.sales.quantity),
   Text(_ctrl.sales.month),

Upgrading to PHP8.1 on CentOS 7.x

Ken Ng — Fri, 06 May 2022 11:11:49 +0000

Laravel 9 which has been released recently dropped the support for PHP7.x, and now it can only run on PHP8.0-PHP8.1.

PHP8.1 is shipped with a few nice features like Enums, readonly class property and etc. The introduction of the Enums finally allows you to type-hint permissible values accepted by a variable than resort to using docblock typehints, or third-party “fake enum” packages.

Let's dive into how to upgrade our server to PHP8.1 from PHP8.0.

sudo yum -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
sudo yum -y install https://rpms.remirepo.net/enterprise/remi-release-7.rpm
sudo yum -y install yum-utils

sudo yum-config-manager --disable 'remi-php*'
sudo yum-config-manager --enable remi-php81

sudo yum install -y php81-php php81-php-fpm php81-php-mysql php81-php-gd php81-php-curl php81-php-mbstring php81-php-xml php81-php-bcmath php81-php-sqlite3 php81-php-zip

Two issues encountered during the upgrade

1. Conflicts of library

file /usr/lib64/libzip.so.5 from install of libzip5-1.8.0-2.el7.remi.x86_64 conflicts with file from package libzip-1.3.2-1.amzn2.0.1.x86_64
Solution: remove the existing package then run the installation of php81 again
$ yum remove libzip-1.3.2-1.amzn2.0.1.x86_64

2. php-fpm is not enabled and started properly

Check using systemctl

$ systemctl list-unit-files | grep fpm
php81-php-fpm.service                         disabled

Let's enable and starts it, then check its status

$ systemctl enable php81-php-fpm.service
$ systemctl start php81-php-fpm.service

$ systemctl status php81-php-fpm.service
● php81-php-fpm.service - The PHP FastCGI Process Manager
   Loaded: loaded (/usr/lib/systemd/system/php81-php-fpm.service; enabled; vendor preset: disabled)
   Active: active (running) since Fri 2022-05-06 18:21:15 +08; 6min ago
 Main PID: 16011 (php-fpm)
   Status: "Processes active: 0, idle: 5, Requests: 0, slow: 0, Traffic: 0req/sec"
    Tasks: 6
   Memory: 8.9M
   CGroup: /system.slice/php81-php-fpm.service
           ├─16011 php-fpm: master process (/etc/opt/remi/php81/php-fpm.conf)
           ├─15897 php-fpm: pool www
           ├─15898 php-fpm: pool www
           ├─15899 php-fpm: pool www
           ├─15900 php-fpm: pool www
           └─15901 php-fpm: pool www

Another issue noticed is php-fpm does not read php-fpm config that we have setup in /etc/php-fpm.d. From the output of systemctl status command, we can see that configuration read is located at /etc/opt/remi/php81/php-fpm.conf.

Edit this file to update the conf directory to be read

;include=/etc/opt/remi/php81/php-fpm.d/*.conf
include=/etc/php-fpm.d/*.conf

Now restart the php-fpm service again

$ systemctl restart php81-php-fpm.service 
$ systemctl status php81-php-fpm.service 
● php81-php-fpm.service - The PHP FastCGI Process Manager
   Loaded: loaded (/usr/lib/systemd/system/php81-php-fpm.service; enabled; vendor preset: disabled)
   Active: active (running) since Fri 2022-05-06 18:30:07 +08; 32min ago
 Main PID: 16296 (php-fpm)
   Status: "Processes active: 0, idle: 21, Requests: 30, slow: 0, Traffic: 0req/sec"
    Tasks: 22
   Memory: 118.6M
   CGroup: /system.slice/php81-php-fpm.service
           ├─16296 php-fpm: master process (/etc/opt/remi/php81/php-fpm.conf)
           ├─16297 php-fpm: pool app.xxx.com
           ├─16298 php-fpm: pool app.xxx.com

Instead of the www pool, we can see that it's now serving the pool for the website app.xxx.com that we have set up in the pool configuration.

That's all for it!

Small Things to note running dockerized Laravel testing with Github Actions

Ken Ng — Wed, 21 Jul 2021 04:02:13 +0000

It’s always good to test your app on code changes so that buggy code never goes to production. Github Actions is a sweet feature to use for continuous integration. For a free account, you have 2000 mins/month to use. Today, let’s setup dockerized Laravel unit testing using it.

tldr;
The final workflow at .github/workflows/testing.yml look like this

name: Laravel testing

on:
    push:
        branches:
            - release

jobs:
    phpunit:
        runs-on: ubuntu-20.04
        strategy:
            fail-fast: true

        container:
            image: kenngsimply/laravelapp:v1

        services:
            db-tests:
                image: mysql:5.7
                env:
                    MYSQL_ROOT_PASSWORD: <YOUR-ROOT-PASSWORD>
                    MYSQL_USER: <YOUR-DB-USER>
                    MYSQL_PASSWORD: <YOUR-DB-USER-PASSWOD>
                    MYSQL_DATABASE: <YOUR-DB-NAME>
                ports:
                    - 3306:3306
            redis:
                image: redis:6-alpine
                ports:
                    - 6379:6379

        steps:
            - name: Checkout
              uses: actions/checkout@v2
            - name: Install composer dependencies
              run: |
                composer install
            - name: Prepare Laravel Application
              run: |
                cp .env.testing .env
                php artisan key:generate
            - name: Migrate and seed
              run: |
                php artisan migrate --seed
            - name:
              run: |
                php artisan redis:init
            - name: Run Testsuite
              run: php artisan test

Note:

Since phpunit will be using .env.testing when it’s exists, we will copy it as .env in the test environment
Since we specify container, the jobs will be running in the laravelapp docker container instead of in the runner machine. This simplifies the network access to service containers.
services.<name> will become your docker container’s hostname. For our example, the MySQL database container hostname will be db-tests. So in your .env.testing, make sure to set the DB_HOST=db-tests. Again this is because the jobs are running inside the docker. If it's running in the runner machine, then we would have to change it to DB_HOST=localhost. Refers to this good tutorial on service container for better understanding.
If you having a connection issue with MySQL, you can try ping it using curl as one of the run step , Example curl db-tests:3306 --ouput -
We use fetch-depth: 1 so that we are not cloning the entire git history. In fact, this is the default behaviour of actions/checkout@v2, we just make it explicit here. Refer to the doc for all the inputs that are available.
fail-fast is by default set to true, we just make it explicit here.

Here’s a sample of .env.testing

APP_NAME="My Sample Laravel App"
APP_ENV=testing
APP_KEY=
APP_DEBUG=true
APP_URL=http://localhost

LOG_CHANNEL=stack

DB_CONNECTION=mysql
DB_HOST=db-tests
DB_PORT=3306
DB_DATABASE=
DB_USERNAME=
DB_PASSWORD=

REDIS_CLIENT=phpredis
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_DB=0
REDIS_PREFIX='redis_test_'

CACHE_DRIVER=database
CACHE_PREFIX='cache_'   

TELESCOPE_ENABLED=false