ProcessWire 2.6.20 and surprise: ProcessWire 3.0 alpha 1

Two ProcessWire versions this week!

ProcessWire 2.6.20

This week (and last week) we continued on the path of keeping up-to-date with GitHub issue reports and covering all the issues that come up. There have yet to be any major issues reported, so we're focused on just minor things here, and it seems like we're about ready for release of 2.7. We're aiming to release it at the end of October, 1-2 weeks from now. Since the quantity of issues to cover has been getting smaller, we've taken the opportunity to put some more work into the 3.x branch of ProcessWire, which is also covered in this post.

A couple of improvements were added in 2.6.20 as well. Specifically, the empty-trash and page-clone functions have been updated to support much larger scale operations. Previously some people were running into issues when trying to empty the trash when it had thousands of items in it, or recursively clone a branch of pages that had thousands of pages. Following this week's update, those operations can now be performed on a larger scale. These still can't be performed on an infinite scale though. For instance, if you've got a 100k pages in your trash, it'll probably take several empty operations before they are all cleared out.

If you have a chance, please grab the latest dev branch version 2.6.20 and let us know how it works for you!

ProcessWire 3.0 alpha 1

We are making progress on ProcessWire 3.0 and have created a new branch on GitHub for it, called the devns branch. This is work in progress, so do not use it in production, as things are still likely to change. However, if you are interested in following it, feel free to give it a try.

How is this version different from 2.6/2.7?

Currently it's identical in functionality to the current dev branch (2.6.20). Where it differs greatly is on the code side. Here's what's different in ProcessWire 3.0 alpha 1:

  • The biggest difference: it runs in its own PHP namespace. Previous versions of ProcessWire ran in the root namespace. Since this is the biggest difference, much of this post will focus on this change.

  • It supports the ability for modules to optionally use alternate namespaces. Modules that use dedicated namespaces also benefit from more autoloading options.

  • Multi-instance ProcessWire support is partially there already, though not quite ready for you to use just yet. What is multi-instance support? That means you can have one script that's issuing API calls to multiple installations of ProcessWire, different databases, etc. Imagine the data sharing possibilities here.

  • There's been a lot of code cleanup, getting rid of old-style API calls, deprecated methods and more. A major version change (2x to 3x) is always a good time to drydock, clean out the basement, scrub the floors and put on a fresh coat of paint.

  • Composer support is partially there and in progress. We've registered a packagist account called "processwire" so ProcessWire 3.x will be available as a library from there called "processwire/processwire" in the near future as well.

The above is how this version is different now, but of course there's a lot more on the way.

What benefits will using namespaces bring?

It kind of depends on the developer (you). For many it simply won't matter. For others, it'll be a breakthrough. Whether it matters to you personally or not, it's a good thing for the ProcessWire project. It positions ProcessWire well for the future, helps how ProcessWire is perceived relative to other projects, and will help attract new users to ProcessWire. Here's a few more details on the technical benefits:

Using namespaces means that ProcessWire can be integrated with other PHP projects more easily, further strengthening its usability as a PHP framework. As an example, take our old friend WordPress (maybe not the best example, but at least it's one everybody will recognize). You could not easily include ProcessWire from WordPress because the two had name collisions on some classes and functions. Since ProcessWire now runs in its own namespace, it can be included in many situations that it could not have before. So if you want to pull a ProcessWire instance/API into a WordPress site (or any other PHP application or framework) now you can. Granted, you could already do that in a lot of cases, but namespaces open the door to being able to do it just about anywhere.

A traditional benefit of using namespaces in PHP is ease of autoloading classes (like the PSR-4 autoloading standard). ProcessWire itself doesn't use a PSR autoloading standard for its own classes and modules, as it already has something better suited to the core and our module system. But it is fully compatible with PSR-4, and even implements its own PSR-4 autoloader for those that want to define their own namespace roots to autoload their own classes from. You can define your own PSR-4 namespaces and corresponding paths using the new $classLoader API variable in ProcessWire 3.0. We'll get into more detail on this in a future post for those that are interested.

In 2010 when the first open source release of ProcessWire came out, namespaces weren't very common among CMS projects, and there wasn't a real compelling case for using them except for dedicated frameworks and other specific needs. Then along came Composer, autoloading standards and more… and today using namespaces is kind of a default assumption and best practice for any PHP project. We're all about best practices, how the project is perceived from outsiders, and how well it adapts to your future needs and scale. Adopting namespaces made a lot of sense for the 3.x major version, even if many of us don't need them immediately.

Namespace considerations for template files

One reason ProcessWire hasn't used namespaces before is that they run a little counter to our philosophy of keeping the API as absolutely simple as possible. Namespaces add verbosity, and if you don't actually need namespaces, then you may find that verbosity annoying. What do I mean by verbosity? I mean namespace ProcessWire; at the top of your PHP files, or an alternate namespace if you so choose. That's really all there is to it. It's not much verbosity granted, but it's there nevertheless. If it's useful to you, you'll love it. But if it's not, then you may perceive it as unnecessary technical jargon.

The good news is that use of namespaces in your template files will be optional in many (or most) cases. But there will be some cases where template files will need the ProcessWire namespace added to them in order to recognize the new context. Though 3.x also comes with a 2.x compatibility mode $config->compat2x = true; that lets most sites designed for 2.x continue running normally in 3.x, without overhead.

ProcessWire 3.x will also come with a template compiler that takes care of making sure templates are 3.x compatible at runtime. It does this by automatically updating them with a namespace (when needed) without you having to think about it. Compiled templates will also provide some other benefits, such as the ability to natively support other template engines and have them automatically compiled to PHP every time a change is made. A simple example would be automatically converting markup like <a href='config.urls.root'> to <a href='<?php echo $config->urls->root; ?>'> which could simplify the appearance of your markup during development. While ProcessWire's core doesn't (and won't) use full template engines by design, compiled templates will open up an interesting new class of 3rd party modules available for ProcessWire installations that wasn't previously possible.

When will using a namespace be necessary in template files? When you use ProcessWire's wire() function (or other wire* functions), or if you refer to ProcessWire core class names like Page and PageArray in your template files. Use of API variables ($page, $pages, $modules, etc.) does not require use of namespaces. In fact, all of ProcessWire's default site profiles were able to run without any changes to them. Nevertheless, we think many will find it to be worthwhile to declare a namespace at the top of your template files when creating new sites in ProcessWire. For those that don't care about namespaces, you can ignore them in your template files unless PHP complains.

Namespace considerations for 3rd party modules

When it comes to 3rd party module developers, there's a more certain chance that modules will need to be updated for this namespace change. Compatibility mode will enable many 3rd party modules to run without a change. But when a module is made natively for 3.x it will want to either use the ProcessWire namespace, or declare its own. Essentially, a module can be updated for 3.x support simply by adding namespace ProcessWire; at the top of the module file.

If a 3rd party module developer wants to go further and declare their own namespace, they can. The ProcessWire core will identify it and call it appropriately. Further, modules that declare their own namespace will automatically receive PW's PSR-4 autoloader for any class/file dependencies the module might have, rather than having to require() or include() them manually. Though unless the module is particularly broad in scope, we suspect that most module authors will simply use the ProcessWire namespace. But for modules that include other classes/files, it might make a lot of sense to take advantage having your own namespace.

When will ProcessWire 3.x be released?

ProcessWire 3.x likely won't be released in stable form till spring 2016. While we've made a lot of progress already, there's still much more to do. However, we're really happy that we can already bring some of the goods to you today, and we'll have a lot more coverage of 3.x in upcoming blog posts.

How many more versions will be in the 2.x branch?

After ProcessWire 2.7, we'll continue updating both the 3.x and 2.x branches with the same features, optimizations and fixes. 2.7 may be the last major version on the 2.x branch, but there will likely be several minor versions. If there's a compelling reason for there to be a 2.8 then there will be, but we'll play that by ear. Our plan is to make sure that 3.x is an easy and minor upgrade from 2.x by the time it is released as stable.

What namespaces does ProcessWire use?

ProcessWire's core uses a single "ProcessWire" namespace, at least from the perspective of the public API. Modules and templates may also use this namespace if they want to, or they may define their own namespaces as they see fit. ProcessWire may also use the root namespace, but only if you enable 2.x compatibility mode with $config->compat2x = true; in your /site/config.php file.

ProcessWire 3.x's modules system has full support for whatever namespace the module developer chooses. We will be recommending that module developers use a custom namespace in cases where they may be defining other classes outside of their module, as this limits the possibility of name collisions with other modules that might define similar class names.

The core doesn't use a complex hierarchy of namespaces like some other frameworks because it simply doesn't need them. We also don't want to introduce unnecessary verbosity to our public API. Our autoloading mechanism has no namespace dependency, and our system is based on a bootable API rather than a framework of components that can be used in isolation. ProcessWire's core may however use additional namespaces internally for components that won't be seen on the public API.

Where to get 3.0 alpha 1?

This version is available as the devns branch on GitHub. Go there to download the zip or clone it with git. Just remember this version is an alpha preview and not something you should start upgrading your sites to yet! :)

If you have any questions or comments on the ProcessWire 3.x branch or any of the new things that it brings, we'd enjoy hearing from you! Please comment below. Be sure to read Teppo's ProcessWire Weekly this weekend!


  • Adrian Mak

    Adrian Mak

    • 8 years ago
    • 20

    looking forward 3.x dev XD

  • Antti


    • 8 years ago
    • 21

    API stays the same and simple. Only new thing to learn is adding namespace on top of the file and prefixing methods when needed. In simple template code you don't have to even do that, since templates will be compiled.

    • Steffen


      • 8 years ago
      • 00

      What does it actually mean "templates will be compiled" in a php/processwire world?

  • Adrian Mak

    Adrian Mak

    • 8 years ago
    • 10

    I'm exciting about a glance of 3.x features mentioned above.
    I'm hoping for that major version will still keeping PW's api clean and simple.
    Based on my experience in Drupal, the APIs get more and more complicated for each major version upgrade. Even for an existing Drupaler, it is still quite a bit to follow.

    • Pete


      • 8 years ago
      • 10

      +1 What Antti said. Basically the API methods you use with ProcessWire are abstracted so that even in the unlikely event of the entire codebase being rewritten, you would still be able to use $pages->find('selector') and all the other API goodness no matter what. There are no plans to change this, so the API itself is pretty future-proof no matter what happens behind the scenes.

      Whilst the API will not change in terms of breaking what's already there, things might get added to it over time in terms of new functionality (this happens currently), but a lot of effort has gone into making sure that for most people the eventual change to 3.x will be as painless as possible.

      We know that if you have dozens of clients and suddenly someone forces you onto a new branch that can be a massive pain if you keep them all up to date which is why Ryan has been working hard to make sure as little work as possible is required for devs to adopt 3.x and not cause the headaches that some of us may have experienced on other platforms.

    • Ryan


      • 8 years ago
      • 10

      These guys already said it well–there won't be any API changes. While compiled templates will be an option, they are far from a necessity because all of PW's API variables ($pages, $page, $user, $input, etc.) will continue to be accessible to your template files just as they are in 2.x, regardless of whether you declare a ProcessWire namespace in your template file.

      It's only when you get into calling a PW function like wire('api_var'); wireDate(); etc., or creating a new PW object like: $a = new PageArray(); that PHP will throw an error if you haven't specified the ProcessWire namespace at the top of your file. That error can easily be resolved by any one of these:

      1. Adding "namespace ProcessWire;" to the top of your file; or…

      2. Enabling the "compiled templates" option; or…

      3. Enabling 2.x compatibility mode with $config->compat2x=true; in your /site/config.php file; or…

      4. Prefixing the PW function/class name with \ProcessWire\, like this: \ProcessWire\wire('api_var');

      For me, I will use option 1 when creating new sites, or option 2 when I need some other benefit from compiled templates.

      For existing sites that I want to upgrade to PW 3.x, I won't do anything unless PHP complains. If it does, and I don't want to add "namespace ProcessWire;" to the top of that site's template files, then I'll use option 2 or 3.

      I won't use option 4 unless I'm wanting to use some alternate, non-ProcessWire namespace in my template files. I haven't had the need for that before, but some broader scope applications in PW might benefit form it. Some may already be doing this even in PW 2.x.

  • organizedfellow


    • 8 years ago
    • 00

    So this would really simplify the core multisite ability, thus making subdomains easier to manage as a single installation?

  • Bernhard


    • 8 years ago
    • 11

    Thanks for the insights!
    Would this also make it possible to get access to a 2x installation of processwire or can one only share data/api between two (or more, right?) Installations of 3x?

    • Ryan


      • 8 years ago
      • 21

      When using multi-instance, any instances are sharing the same PW core because PHP can't redeclare the same class multiple times in one execution. So they would all be running from the context 3.x. The databases they are connecting to don't necessarily have to be from a 3.x installation of PW though, but it's a good idea if they are; and it's also a good idea of they are running the same or similar set of modules.

      Multi-instance will be handy in a lot of situations, but one example I can think of is here on this site. Our, and main are all running under separation PW installs. With multi-instance, all those sites could talk to one another from the API side, without using web services. For a simple example, I could setup the main site search engine to also search the modules and cheatsheet sites, and include their matches in the search results. It will be a nice and simpler alternative to using web services/feeds when you have multiple PW installs that you control.

    • juno


      • 8 years ago
      • 10

      For the more front-end oriented Processwirerers, this was a good/helpfull read:

    • Alan


      • 8 years ago
      • 10

      This is exciting news Ryan (& team). There is little I respect quite as much as the elegance of CSS (thanks Håkon Wium Lie (I am first and foremost a foreground guy)) but on the backend, PW is my CSS—the origins, direction, management and supporters are brilliant. I am so very glad I went PW after leaving the venerable Textpattern.

    • ryan


      • 8 years ago
      • 00

      Another test

    • Sephiroth


      • 8 years ago
      • 10

      Finally a long wait.... I am going to get the Alpha and start working on it and also promise to push more code to 3.0. Good work team

    • ryan


      • 8 years ago
      • 00

      test test test


      Latest news

      • ProcessWire Weekly #511
        In the 511th issue of ProcessWire Weekly we'll cover the latest core updates, introduce a new third party module called Auto AVIF, and more. Read on! / 25 February 2024
      • Using date range fields in ProcessWire
        This week we'll take a detailed look at the newest addition to the ProFields set of modules: the Date Range Fieldtype and Inputfield.
        Blog / 24 November 2023
      • Subscribe to weekly ProcessWire news

      “We chose ProcessWire because of its excellent architecture, modular extensibility and the internal API. The CMS offers the necessary flexibility and performance for such a complex website like ProcessWire offers options that are only available for larger systems, such as Drupal, and allows a much slimmer development process.” —xport communication GmbH