Rodrigo Primo 2:15 pm on October 23, 2025
Tags: codingstandards ( 6 ), PHP ( 75 ), WPCS ( 8 )

Coding Standard Proposal: Make it explicit that PHP files must use the .php extension

The current WordPress Coding Standard does not specify which file extensions should be used for PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher files. This proposal establishes that only the .php file extension should be allowed for PHP files.

Motivation

While web servers like ApacheApache Apache is the most widely used web server software. Developed and maintained by Apache Software Foundation. Apache is an Open Source software available for free. and NginxNGINX NGINX is open source software for web serving, reverse proxying, caching, load balancing, media streaming, and more. It started out as a web server designed for maximum performance and stability. In addition to its HTTP server capabilities, NGINX can also function as a proxy server for email (IMAP, POP3, and SMTP) and a reverse proxy and load balancer for HTTP, TCP, and UDP servers. https://www.nginx.com/. can be configured to execute files with various extensions as PHP (e.g., .php3 and .phtml), the .php extension is the only one universally supported. If PHP files do not use the .php extension, there is a risk that scripts will not work on some web servers. For example, a default Debian installation using Apache and mod_php parses .php, .phtml, and .phar as PHP, whereas a default Fedora installation using Apache and mod_php parses only .php and .phar as PHP. This means that a pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party using .phtml file extensions will work on Debian, but not on Fedora (and may inadvertently render code in plain text). Therefore, for code portability, compatibility, and security, it should be agreed and checkable that only .php extensions are used for PHP files.

Another benefit of the change proposed here is that if all PHP files use the .php extension, we can be sure that they will be checked by tools like PHPCSPHP Code Sniffer PHP Code Sniffer, a popular tool for analyzing code quality. The WordPress Coding Standards rely on PHPCS..

Proposed change to the handbook

Add a new item to the General section of the PHP Coding Standard Handbook as follows:

Title: File Extension

Content: PHP files must use the .php file extension.

References

This was originally proposed by Gary Jones in this WPCS issue.

#codingstandards, #php, #wpcs

Props @dingo_d, @garyj, and @jrf for reviewing this post.

Dennis Snell 5:06 pm on October 23, 2025

This is an interesting proposal, as I had no idea people were using other file extensions — especially .php3! I checked and confirmed that only .php is used in CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress..

How prevalent were non-.php files in your discovery for this proposal? How frequently are plugins or themes in the directory using them? Have they only been seen in proprietary plugins and themes?
- Bernhard Kau 7:20 pm on October 23, 2025
  
  I was also wondering if this is (still) an issue. I have not seen a single pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party using a different extension than `.php` for its PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher files.
- Rodrigo Primo 9:43 pm on October 23, 2025
  > How prevalent were non-.php files in your discovery for this proposal? How frequently are plugins or themes in the directory using them? Have they only been seen in proprietary plugins and themes?
  
  @garyj, as the original author of the issue that led to the creation of this proposal can correct me if I’m wrong, but my understanding is that this is more about making an implicit expectation explicit than about creating a rule to address a problem that is encountered frequently in the WP ecosystem.
  
  That said, I did a quick search of a local copy of the WP.org plugins repository to understand the scope. I found approximately 449 plugins (excluding vendor directories) that contain files with alternative PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher extensions:
  - .phtml (3,287 files)
  - ~~.phpt (1,056 files)~~ (edited: I shouldn’t have included `.phpt` files as they are not affected by this proposal)
  - .phar (80 files)
  - .phps, .php4, .php5, and others (98 files combined)
  Total: ~4,500 files across 449 plugins
  
  Important caveat: This is just a count of files with these extensions – I did not analyze how these files are actually used.
  - Gary Jones 9:48 pm on October 23, 2025
    
    Yes, this isn’t a proposal to tackle a significant problem. In fact, it’s one of those where the vast majority of developers are already following it (though not everyone, as the stats above show), but it’s precisely that already-high adoption which makes it a great candidate for the coding standards. The proposal ratifies what is already happening, but it allows QA and other developer-focused tooling to streamline their efforts by not having to build support for potential extensions.
    - Dennis Snell 2:36 pm on October 28, 2025
      
      it allows QA and other developer-focused tooling to streamline their efforts by not having to build support for potential extensions
      
      It would really surprise me if many of our QA tools support these other extensions, so if I’m properly understanding your comment, it seems like this rule wouldn’t change that.
      
      I ask here because it concerns me how frequently our Coding Standards can backfire on us in unexpected ways and risk even reducing quality through implicit incentive structures (adding this file prevents breakage on XYZ but I don’t know how to get it past WPCSWordPress Community Support A public benefit corporation and a subsidiary of the WordPress Foundation, established in 2016. so I’ll just rename it to make the linter happy and ignore the breakage).
      
      If we reject files, which might actually be legitimate within their context, how do we get out of the way when the tooling is wrong? How can we ensure that we don’t frustrate people by rejecting their valid work? In this case, what the analogue to an ignore comment?
      
      this isn’t a proposal to tackle a significant problem
      
      That’s a relief to know! I am hoping we can continue gathering note of which rules and rejections we enforce which aren’t tackling serious problems and prune them out of our PHPCSPHP Code Sniffer PHP Code Sniffer, a popular tool for analyzing code quality. The WordPress Coding Standards rely on PHPCS./WPCS workflows. If they aren’t a problem, why add the runtime overhead, the misconfigurations, and the obstacles for people who are wanting to contribute?
      
      I’m surprised and curious about those ~4,500 files, especially the .phtml ones. Thanks so much for gathering that data!
      
      Aren’t the .phpt files almost certainly test suites? Surely our goal isn’t to eliminate tests…? Also I wonder if the .phar are vendored includes of Composer packages.
      
      @rodrigosprimo do we have any knowledge of the age of these? I think everything non-.php was basically gone as of PHP5. Also do you have a ballpark estimate for how many total files and plugins there are? Are 3,000 and 449 wildly-unexpected counts or a tiny fraction of plugins abandoned plugins (against which this rule would never apply since they aren’t being maintained)?
      
      Has any new code within the past ten years used anything other than .php?
      - Rodrigo Primo 5:53 pm on October 29, 2025
        
        Thanks for taking the time to read this proposal and share your questions, @dmsnell!
        It would really surprise me if many of our QA tools support these other extensions, so if I’m properly understanding your comment, it seems like this rule wouldn’t change that.
        
        I think there may be a slight misunderstanding about Gary’s point. The idea is not to change the extensions that the tools currently support.
        
        Consider a pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party that for whatever reason starts using `.phtml`. By default, those files won’t be scanned by PHPCSPHP Code Sniffer PHP Code Sniffer, a popular tool for analyzing code quality. The WordPress Coding Standards rely on PHPCS./WPCSWordPress Community Support A public benefit corporation and a subsidiary of the WordPress Foundation, established in 2016. and thus potential coding standard violations won’t be flagged. By establishing that PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher code must use `.php`, we close this coverage gap through policy.
        If we reject files, which might actually be legitimate within their context, how do we get out of the way when the tooling is wrong? How can we ensure that we don’t frustrate people by rejecting their valid work? In this case, what the analogue to an ignore comment?
        
        If this proposal is approved and added to the handbook, there are still some details to discuss about how to implement this in WPCS (or at least there are some details that are not clear to me, but @garyj or someone else might have thought about it already).
        
        Generally speaking, in the hopefully rare instance where there is a legitimate reason to use a non-.php extension, developers can exclude it by adding a `exclude` tagtag A directory in Subversion. WordPress uses tags to store a single snapshot of a version (3.6, 3.6.1, etc.), the common convention of tags in version control systems. (Not to be confused with post tags.) to the ruleset XML file or using the `// phpcs:disable` comment in the offending file.
        Aren’t the .phpt files almost certainly test suites? Surely our goal isn’t to eliminate tests…?
        
        Good point! Sorry for the confusion, I shouldn’t have included them in the statistics above. `.phpt` files are not part of this proposal – they’re typically test specification files, not executable PHP code.
        Also I wonder if the .phar are vendored includes of Composer packages.
        
        I’m not sure I understand what you mean by “vendored includes of Composer packages”. For context, I excluded the vendor/ directory when checking file extensions in the WP.org plugins repository. I was surprised to find `.phar` files in plugins, especially outside of vendor directories.
        @rodrigosprimo do we have any knowledge of the age of these? I think everything non-.php was basically gone as of PHP5. Also do you have a ballpark estimate for how many total files and plugins there are? Are 3,000 and 449 wildly-unexpected counts or a tiny fraction of plugins abandoned plugins (against which this rule would never apply since they aren’t being maintained)?
        
        When I gathered those numbers, I didn’t check the age of the 449 plugins. Anecdotally, I checked a few and most were either closed or hadn’t been updated in a couple of years, which matches what I expected. Those plugins represent a tiny fraction of the WP.org plugins repository. My local copy (updated a couple of months ago) contains 94,555 plugins.
        Has any new code within the past ten years used anything other than .php?
        
        I don’t have this data. I’m curious though – how does this factor into evaluating the proposal? My understanding is that coding standards document best practices and expectations regardless of current compliance rates. Even if no new code has used non-.php extensions in years, wouldn’t the security/portability concerns and the value of explicit documentation remain?
        
        Dennis Snell 2:41 am on October 30, 2025
        
        developers can exclude it by adding a exclude tagtag A directory in Subversion. WordPress uses tags to store a single snapshot of a version (3.6, 3.6.1, etc.), the common convention of tags in version control systems. (Not to be confused with post tags.) to the ruleset XML file or using the // phpcs:disable comment
        
        If the tooling doesn’t scan the files with a different extension, how would the ignore-comment be recognized? Or would the idea be that WPCSWordPress Community Support A public benefit corporation and a subsidiary of the WordPress Foundation, established in 2016. would check every potential kind of file that could contain PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher and reject it if it’s not .php?
        
        excluded the vendor/ directory when checking file extensions
        
        “Vendoring” in the general sense that someone has brought in a third-party library by copying the source code into the project’s own source code. These are, by convention, stored in vendor/ but there is no special privilege that directory has outside of Composer. There’s no requirement that projects vendor their code inside of vendor/.
        
        As was the case with .phpt it’s also quite likely that plugins have .phar libraries for building and testing purposes rather than runtime.
        
        coding standards document best practices and expectations regardless of current compliance rates. Even if no new code has used non-.php extensions in years, wouldn’t the security/portability concerns and the value of explicit documentation remain?
        
        There’s a lot we could all discuss in this, but with respect to your direct question I did overlook that this was to the guidebook (as @garyj) pointed out and not to WPCS itself.
        
        Still, my point is more about asking if we are pushing solutions in search of problems. It seems non-controversial to observe that the PHP world writes code in .php files. Do we also mandate that PNG files are stored with .png and JPEG files as .jpeg? Is .jpg a violation of best practices that should be rejected within the WordPress community?
        
        Rodrigo Primo 3:10 pm on October 31, 2025
        
        If the tooling doesn’t scan the files with a different extension, how would the ignore-comment be recognized? Or would the idea be that WPCSWordPress Community Support A public benefit corporation and a subsidiary of the WordPress Foundation, established in 2016. would check every potential kind of file that could contain PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher and reject it if it’s not .PHP?
        
        That is one of the open questions, at least to me, that will need to be discussed if this proposal is approved and the rule added to the handbook.
        There’s no requirement that projects vendor their code inside of vendor/.
        
        Thanks for the clarification. Typically, it is recommended to exclude the `vendor` directory from the PHPCSPHP Code Sniffer PHP Code Sniffer, a popular tool for analyzing code quality. The WordPress Coding Standards rely on PHPCS. scan. If there are composer packages or other third-party code in other locations, those should likely be excluded as well.
        Still, my point is more about asking if we are pushing solutions in search of problems. It seems non-controversial to observe that the PHP world writes code in .php files. Do we also mandate that PNG files are stored with .png and JPEG files as .jpeg? Is .jpg a violation of best practices that should be rejected within the WordPress community?
        
        If there were security/portability concerns with using different file extensions for those image types, probably yes. But that is not the case as far as I know.
        Thank you both for your work on communication @garyj and @rodrigosprimo. My thoughts are out here and I wanted to respond to your questions, though I also want to allow for other voices to surface and so will step back.
        
        Thanks for taking the time to read this proposal and raise your questions, @dmsnell!
      - Gary Jones 7:08 pm on October 29, 2025
        
        It would really surprise me if many of our QA tools support these other extensions, so if I’m properly understanding your comment, it seems like this rule wouldn’t change that.
        
        PHPCSPHP Code Sniffer PHP Code Sniffer, a popular tool for analyzing code quality. The WordPress Coding Standards rely on PHPCS. itself accepts an `–extensions` arg (which I believe would be needed for any PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher file with the wrong extension to be scanned in the first place), as do PHPLOC, and phpDocumentor has similar. Same for PHPMD and Deptrac.
        
        I ask here because it concerns me how frequently our Coding Standards can backfire on us in unexpected ways and risk even reducing quality through implicit incentive structures (adding this file prevents breakage on XYZ but I don’t know how to get it past WPCSWordPress Community Support A public benefit corporation and a subsidiary of the WordPress Foundation, established in 2016. so I’ll just rename it to make the linter happy and ignore the breakage).
        
        Your general concern about coding standards (or rather the use of QA tooling to enforce them) doesn’t seem specific to this proposal.
        
        If we reject files, which might actually be legitimate within their context, how do we get out of the way when the tooling is wrong? How can we ensure that we don’t frustrate people by rejecting their valid work? In this case, what the analogue to an ignore comment?
        
        You’re jumping ahead to the implementation details of WordPressCS. This proposal is about changing the handbook to incorporate the rule, as a way to normalise / codify (in the documentation sense) what is mostly already happening. That rule can exist in the handbook, and inform the developers in the community, regardless of whether there is automated QA tooling to help enforce it. Not everything in the handbook is covered by WordPressCS.
        
        That said, as Rodrigo noted, there are ways for developers to ignore this rule for specific files, or the sniffsniff A module for PHP Code Sniffer that analyzes code for a specific problem. Multiple stiffs are combined to create a PHPCS standard. The term is named because it detects code smells, similar to how a dog would "sniff" out food. can be written with a default but overridable list of extensions if flexibility is desired, though that would then be at odds with what the handbook would require of developers.
        
        why add the runtime overhead
        
        Again, you’re thinking in PHPCS, and not in the handbook.
        
        But I just created a simplified version of a file extension checking sniff, and it scanned 10000 files in 0.7 seconds, so runtime overhead would seem negligible.
        
        the obstacles for people who are wanting to contribute?
        
        This is such a simple rule for the handbook, that I think it actually removes an obstacle for contributors; there’s no ambiguity about what file extension PHP files in WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. or plugins or themes should have. Our requirements around whitespace and documentation standards are a much bigger blockerblocker A bug which is so severe that it blocks a release. to contributing than this rule would be.
        
        Dennis Snell 2:51 am on October 30, 2025
        
        You’re jumping ahead to the implementation details of WordPressCS.
        
        Thanks for pointing that out.
        
        Are you saying that there’s no intention of enforcing this through WPCSWordPress Community Support A public benefit corporation and a subsidiary of the WordPress Foundation, established in 2016. after adding it to the guide?
        
        it actually removes an obstacle for contributors; there’s no ambiguity about what file extension PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher files in WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. or plugins or themes should have
        
        Ideologically maybe, but evidentially I still wonder if the justification is formulated after the fact.
        
        Thank you both for your work on communication @garyj and @rodrigosprimo. My thoughts are out here and I wanted to respond to your questions, though I also want to allow for other voices to surface and so will step back.
    - Mary Hubbard 8:41 pm on October 28, 2025
      
      I share the same concerns as @dmsnell and we should resolve those questions. Though, I think codifying what’s already the norm helps new contributors and can keep tooling clean.
      - Rodrigo Primo 3:20 pm on October 31, 2025
        
        Thanks for your input, @4thhubbard! Gary and I have responded to Dennis’s questions. Please let me know if you need any further clarification or if there are other concerns we should address.
Peter Wilson 10:17 pm on October 31, 2025

I think this would be helpful for the WordPress Coding StandardsWordPress Coding Standards The Accessibility, PHP, JavaScript, CSS, HTML, etc. coding standards as published in the WordPress Coding Standards Handbook.
May also refer to The collection of PHP_CodeSniffer rules (sniffs) used to format and validate PHP code developed for WordPress according to the PHP coding standards., specifically meaning those applied to WordPress CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.. I’ve reviewed a lot of PRs and never seen someone attempt to use another extension but it would be easy enough to miss while doing a review.

As for the wider community making use of the WordPress Coding Standards in their themes and plugins, I think it would be best to make the sniffsniff A module for PHP Code Sniffer that analyzes code for a specific problem. Multiple stiffs are combined to create a PHPCS standard. The term is named because it detects code smells, similar to how a dog would "sniff" out food. configurable so developers can make an allow list of extensions if their project requires it.

Welcome!

Communication

Coding Standard Proposal: Make it explicit that PHP files must use the .php extension

Motivation

Proposed change to the handbook

References

Welcome!

Communication

Motivation

Proposed change to the handbook

References

Share this:

Site resources