KNOWNHOST WIKI

User Tools

Site Tools


developmental:php-error-log-testing-and-troubleshooting

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
developmental:php-error-log-testing-and-troubleshooting [2019/10/11 07:58]
Karson N. [Creating the Error Log]
developmental:php-error-log-testing-and-troubleshooting [2020/06/10 09:52] (current)
Karson N. [Testing Your Changes]
Line 5: Line 5:
 PHP error logging for your site is an optional level of logging that can be enabled to log errors that occur with PHP code. There are several reasons you may choose to enable PHP error logging.  You may want to enable PHP error logging if you're actively developing your site to aid in troubleshooting. If you have encountered the dreaded 'white page of death' error (that error that loads a blank page and tells you nothing regarding what is wrong). Or a "500 error" that doesn't log to the Apache error log as 'real' 500 level errors do, then you will need to enable PHP error logging for your site to find the script error.  Doing so will cause PHP errors to be logged in the location you choose so that you can determine what is causing the error and work to fix it.  PHP error logging for your site is an optional level of logging that can be enabled to log errors that occur with PHP code. There are several reasons you may choose to enable PHP error logging.  You may want to enable PHP error logging if you're actively developing your site to aid in troubleshooting. If you have encountered the dreaded 'white page of death' error (that error that loads a blank page and tells you nothing regarding what is wrong). Or a "500 error" that doesn't log to the Apache error log as 'real' 500 level errors do, then you will need to enable PHP error logging for your site to find the script error.  Doing so will cause PHP errors to be logged in the location you choose so that you can determine what is causing the error and work to fix it. 
  
 +\\
 ===== Planning What Settings To Use ===== ===== Planning What Settings To Use =====
  
 You should decide what log settings you need to set before enabling. Most of the time, you will simply choose to have PHP errors logged to a private log in a location that you specify. If the site is //not// live, then you may also choose to have the errors displayed on the site in the browser. **NOTE:** Displaying PHP errors on a live site is a security issue so do //not// enable this setting on a live site! Here are the recommended settings for a live site: You should decide what log settings you need to set before enabling. Most of the time, you will simply choose to have PHP errors logged to a private log in a location that you specify. If the site is //not// live, then you may also choose to have the errors displayed on the site in the browser. **NOTE:** Displaying PHP errors on a live site is a security issue so do //not// enable this setting on a live site! Here are the recommended settings for a live site:
 +<code>
   log_errors = on   log_errors = on
   error_log = /path/to/docroot/error_log   error_log = /path/to/docroot/error_log
   display_errors = off   display_errors = off
 +</code>
  
 The recommended settings for a development site that is //not// live are below: The recommended settings for a development site that is //not// live are below:
 +<code>
   log_errors = on   log_errors = on
   error_log = /path/to/docroot/error_log   error_log = /path/to/docroot/error_log
   display_errors = on   display_errors = on
 +</code>
  
 Both of the examples shown above do not include an actual path. You may have to create the error_log file, replacing '/path/to/docroot/error_log' with the exact path to the file. I typically place these in the public_html, and then also make a .htaccess rule to prevent unauthorized access to this log. Go ahead and determine what settings you will be using.  Both of the examples shown above do not include an actual path. You may have to create the error_log file, replacing '/path/to/docroot/error_log' with the exact path to the file. I typically place these in the public_html, and then also make a .htaccess rule to prevent unauthorized access to this log. Go ahead and determine what settings you will be using. 
  
 +\\
 ===== Creating the Error Log ===== ===== Creating the Error Log =====
  
Line 26: Line 30:
  
 To create the file under the cPanel user 'cp_user', you would do the following as the user root via SSH (the document root for most cPanel-hosted main domains is the public_html): To create the file under the cPanel user 'cp_user', you would do the following as the user root via SSH (the document root for most cPanel-hosted main domains is the public_html):
 +<code>
   cd /home/cp_user/public_html   cd /home/cp_user/public_html
   touch error_log   touch error_log
   chown cp_user: error_log   chown cp_user: error_log
 +</code>
  
 Also, be sure that the log can be written to by the user (permissions of 644 should be fine for most KnownHost systems). Do the following to view the file: Also, be sure that the log can be written to by the user (permissions of 644 should be fine for most KnownHost systems). Do the following to view the file:
 +<code>
   ls -lah /home/cp_user/public_html/error_log   ls -lah /home/cp_user/public_html/error_log
 +</code>
  
 The permissions should read as follows if set to 644: The permissions should read as follows if set to 644:
 +<code>
 +  -rw-r--r--
 +</code>
  
--rw-r--r-- +\\
 === cPanel User Access === === cPanel User Access ===
  
Line 45: Line 53:
 Log into your user's cPanel account at the following URL (replacing //yourdomain.tld// with your actual domain): Log into your user's cPanel account at the following URL (replacing //yourdomain.tld// with your actual domain):
  
-https://yourdomain.tld/cpanel+[[https://yourdomain.tld/cpanel|https://yourdomain.tld/cpanel]]
  
 Navigate as follows: Navigate as follows:
- +<code> 
-cPanel >> Files >> File Manager+  cPanel >> Files >> File Manager 
 +</code>
  
 Click the File Manager Icon  Click the File Manager Icon 
Line 69: Line 78:
 {{developmental:file-created.png?nolink&1200|}} {{developmental:file-created.png?nolink&1200|}}
  
 +\\
 ===== How to Enable PHP Error Logging ===== ===== How to Enable PHP Error Logging =====
  
 First,  you need to decide whether you should enable PHP error logging via a php.ini file or via .htaccess. This will depend on what PHP Handler you are using. To find out what PHP Handler you are using with a cPanel server, run the following as the root user via SSH: First,  you need to decide whether you should enable PHP error logging via a php.ini file or via .htaccess. This will depend on what PHP Handler you are using. To find out what PHP Handler you are using with a cPanel server, run the following as the root user via SSH:
 +<code>
   /usr/local/cpanel/bin/rebuild_phpconf --current   /usr/local/cpanel/bin/rebuild_phpconf --current
 +</code>
  
 If you are using multiple versions of PHP, you may need to determine what version of PHP your site is using to determine the correct PHP handler.  If you are using multiple versions of PHP, you may need to determine what version of PHP your site is using to determine the correct PHP handler. 
  
 If you lack root access, you can upload a phpinfo file to your site, and then check it to determine your current PHP Handler. To do so, log into cPanel, navigate to the File Manager, click the button to add a file, name the file phpinfo.php, and add the following content: If you lack root access, you can upload a phpinfo file to your site, and then check it to determine your current PHP Handler. To do so, log into cPanel, navigate to the File Manager, click the button to add a file, name the file phpinfo.php, and add the following content:
 +<code>
   <?php phpinfo(); ?>   <?php phpinfo(); ?>
 +</code>
  
 Now, visit your site's phpinfo.php page in the browser: Now, visit your site's phpinfo.php page in the browser:
  
-https://yoursite.tld/phpinfo.php+[[https://yoursite.tld/phpinfo.php|https://yoursite.tld/phpinfo.php]]
  
 Look for "Server API". If you see "Apache 2.0 Handler", then you are using DSO. If you see "CGI/FastCGI" or "CGI", then you are likely using suPHP, CGI, or FastCGI.  Look for "Server API". If you see "Apache 2.0 Handler", then you are using DSO. If you see "CGI/FastCGI" or "CGI", then you are likely using suPHP, CGI, or FastCGI. 
Line 95: Line 107:
 {{developmental:phpinfo-dso.png?nolink&600|}} {{developmental:phpinfo-dso.png?nolink&600|}}
  
 +\\
 ==== suPHP ==== ==== suPHP ====
  
 If you are using suPHP, then you will want to enable logging via the php.ini as shown below (note that you will want to edit //display_errors// accordingly): If you are using suPHP, then you will want to enable logging via the php.ini as shown below (note that you will want to edit //display_errors// accordingly):
 +<code>
   log_errors = on   log_errors = on
   error_log = /path/to/docroot/error_log   error_log = /path/to/docroot/error_log
   display_errors = off   display_errors = off
-  +</code> 
 If the php.ini and error log files do not exist, you will want to create both and make sure to change the ownership of both to the user. The php.ini can be created in the same way as the error_log was as shown in the previous section. If both of these files already exist, then you should make a backup of each before you make any changes. You can make a backup of these files using the //cp// command as the root user as shown below: If the php.ini and error log files do not exist, you will want to create both and make sure to change the ownership of both to the user. The php.ini can be created in the same way as the error_log was as shown in the previous section. If both of these files already exist, then you should make a backup of each before you make any changes. You can make a backup of these files using the //cp// command as the root user as shown below:
 +<code>
   cp -a /path/to/file /path/to/file.backup   cp -a /path/to/file /path/to/file.backup
 +</code>
  
 This command makes a copy of the file with its current ownership and permissions with the '.backup' extension.  This command makes a copy of the file with its current ownership and permissions with the '.backup' extension. 
Line 116: Line 131:
  
 After making copies of any existing error_log files and php.ini files, you can proceed to edit them as needed. Since you have a backup of the error_log, you may decide to clear it before you start writing to it again. If so, you can do so with the following command as the root user: After making copies of any existing error_log files and php.ini files, you can proceed to edit them as needed. Since you have a backup of the error_log, you may decide to clear it before you start writing to it again. If so, you can do so with the following command as the root user:
 +<code>
   > error_log   > error_log
 +</code>
  
 If you are using File Manager, just delete and recreate the file.  If you are using File Manager, just delete and recreate the file. 
Line 123: Line 139:
 After you edit the php.ini file with the details above accordingly and create the error log,  you should start seeing errors written to the file as soon as they are triggered.  After you edit the php.ini file with the details above accordingly and create the error log,  you should start seeing errors written to the file as soon as they are triggered. 
  
 +\\
 ==== DSO ==== ==== DSO ====
  
 If you are using DSO, then you will want to enable logging via the .htaccess as shown below using the php_flag and php_value directives: If you are using DSO, then you will want to enable logging via the .htaccess as shown below using the php_flag and php_value directives:
 +<code>
   php_flag  log_errors on   php_flag  log_errors on
   php_value error_log  /path/to/docroot/error_log   php_value error_log  /path/to/docroot/error_log
   php_flag display_errors off   php_flag display_errors off
 +</code>
  
 It is also a good idea to make a backup of the .htaccess if one exists before making any changes!  You can make a backup of the file using the cp command as the root user as shown below: It is also a good idea to make a backup of the .htaccess if one exists before making any changes!  You can make a backup of the file using the cp command as the root user as shown below:
 +<code>
   cp -a /path/to/file /path/to/file.backup   cp -a /path/to/file /path/to/file.backup
 +</code>
  
 This command makes a copy of the file with its current ownership and permissions with the '.backup' extension. This command makes a copy of the file with its current ownership and permissions with the '.backup' extension.
Line 140: Line 159:
  
 If an error_log already exists, you can make a backup of it as well, then delete it and recreate it with the correct permissions and ownership so that it is empty. To empty the error_log as root, you could just run this command: If an error_log already exists, you can make a backup of it as well, then delete it and recreate it with the correct permissions and ownership so that it is empty. To empty the error_log as root, you could just run this command:
 +<code>
   > error_log   > error_log
 +</code>
  
 Immediately after making such changes, I always watch the Apache error log and reload the site (just to make sure I didn't break the site due to a typo or other mistake). To watch the Apache error log, use the following command via SSH as the root user: Immediately after making such changes, I always watch the Apache error log and reload the site (just to make sure I didn't break the site due to a typo or other mistake). To watch the Apache error log, use the following command via SSH as the root user:
 +<code>
   tail -f /usr/local/apache/logs/error_log   tail -f /usr/local/apache/logs/error_log
 +</code>
  
 If any mistakes were made that would adversely affect the site, they would be logged here upon reloading the site (this isn't a common occurrence, but it is always good to check).  If any mistakes were made that would adversely affect the site, they would be logged here upon reloading the site (this isn't a common occurrence, but it is always good to check). 
Line 152: Line 173:
  
 Finally, to disable access to your error logs, you can add the following to your .htaccess: Finally, to disable access to your error logs, you can add the following to your .htaccess:
 +<code>
   # prevent access to PHP error log   # prevent access to PHP error log
   <Files error_log>   <Files error_log>
Line 158: Line 179:
    Deny from all    Deny from all
   </Files>   </Files>
 +</code>
  
 +\\
 ===== Testing Your Changes ===== ===== Testing Your Changes =====
  
 You may want to test and ensure that your error log is working as desired, especially if you are troubleshooting an error that only occurs intermittently and you are unable to trigger it on demand. You will want to be sure the error log is effectively logging errors so that you can capture the error when it occurs next. First, create a new PHP script as the root user and give it the correct ownership (change 'cp_user' to your cPanel user): You may want to test and ensure that your error log is working as desired, especially if you are troubleshooting an error that only occurs intermittently and you are unable to trigger it on demand. You will want to be sure the error log is effectively logging errors so that you can capture the error when it occurs next. First, create a new PHP script as the root user and give it the correct ownership (change 'cp_user' to your cPanel user):
 +<code>
   touch error_logging_test.php   touch error_logging_test.php
   chown cp_user: error_logging_test.php   chown cp_user: error_logging_test.php
-  +</code> 
 Edit the file with the following content: Edit the file with the following content:
 +<code>
   <?php   <?php
-  error_log("This is a custom error message constructed to test the php error logging functionality of this site.\n");+     error_log("This is a custom error message constructed to test the php error logging functionality of this site.\n");
   ?>   ?>
-  +</code> 
 Now, watch the error log and load your script in the browser: Now, watch the error log and load your script in the browser:
-   +<code> 
-    tail -f /path/to/docroot/error_log +  tail -f /path/to/docroot/error_log 
-  +</code> 
 If your site is my-site.tld, then you will visit my-site.tld/error_logging_test.php  in the browser. This should trigger the error defined within the script to be written to the error log that we've enabled. You should now see the error appear in the error log if error logging is working properly. If your site is my-site.tld, then you will visit my-site.tld/error_logging_test.php  in the browser. This should trigger the error defined within the script to be written to the error log that we've enabled. You should now see the error appear in the error log if error logging is working properly.
  
-You can do the same as the cPanel user using File Manager. You would create the new file named "error_logging_test.php", add the content above, and save. You would then test the script by visiting  my-site.tld/error_logging_test.php in the browser  (replacing my-site.tld with your actual domain). You should now be able to check the error_log and see if the error generated by visiting the script is present. If so, then error logging is working as expected.  If not, please open a support ticket and we'll be glad to help.  +You can do the same as the cPanel user using File Manager. You would create the new file named "error_logging_test.php", add the content above, and save. You would then test the script by visiting  my-site.tld/error_logging_test.php in the browser  (replacing my-site.tld with your actual domain). You should now be able to check the error_log and see if the error generated by visiting the script is present. If so, then error logging is working as expected.  If not, please open a support ticket and we'll be glad to help.
- +
- +
developmental/php-error-log-testing-and-troubleshooting.1570798696.txt.gz · Last modified: 2019/10/11 07:58 by Karson N.