Plans for our next milestone

We have seen some increase in activity with more people downloading our driver and either reporting their successes or reporting any issues they run into – for the SQLSRV driver (sqlsrv_xxxx API) to the PDO_SQLSRV driver (PDO API). We’d like to thank you all for your effort and hope that our responses were quick enough as well as accurate.

To keep things simple, let us call the former the SQLSRV driver (php_sqlsrv.dll) whereas the latter will be the PDO_SQLSRV driver (php_pdo_sqlsrv.dll).

As mentioned in our blog announcing the release of CTP1, we re-architected the code to add PDO support without duplicating code and offers many benefits for the long haul. For convenience, the new architecture diagram is:


Since the main focus of the v2.0 release is adding support for PDO, we planned on the refactoring into the core functional layer first, then the PDO_SQLSRV driver implementation and finally the SQLSRV driver (which is essentially the sqlsrv_xxxx API “re-wiring”).

Since PDO_SQLSRV was very new and we had some challenging choices and make some difficult decisions (as noted by Brian in his blog on some design decisions for our PDO driver), we wanted more time for feedback on PDO_SQLSRV as well as have a window to make design changes to it that can once again be widely tested before we wrap it up and release. Hence we planned on two interim milestones:

  • CTP1: a completed PDO_SQLSRV driver (and package SQLSRV from v1.1); main goal for this release is to get good feedback from the community as well as leave us a larger window for design changes to PDO_SQLSRV.
  • CTP2: a completed SQLSRV driver (including bug fixes), any design changes & bug fixes required for PDO_SQLSRV based on feedback; main goal for this release is to give the community a chance to catch regressions in SQLSRV and validate design changes in PDO_SQLSRV.

Per the plan, we completed PDO_SQLSRV for CTP1 and released it on April 19. In addition to the feedback from the community, we also got some early feedback from the Commerce Guys (who, as noted in our CTP1 release blog, are developing the Drupal 7 module to support SQL Server and partnered with us to get some pre-release binaries). It is interesting to note that we received feedback and bug reports on the forum, blog, email, and even twitter.

We deliberated on all the feedback and decided to make a few design changes to better meet the needs and expectations of the PHP community. Unfortunately, some of these are  breaking changes and we think it is best to share these with you sooner rather than later and avoid any nasty surprises.

  1. PDO::__construct(): we are moving the Connection Options away from the driver_options[] array to the DSN. While the previous design was completely valid per PDO and a familiar programming model with SQLSRV, the new design makes PDO_SQLSRV more API compatible with the other PDO implementations and thus makes it easier on the database component of the application/framework.

    What this means is that all the Connection Options (well, at least those supported by PDO_SQLSRV) will now have to specified in the DSN string only. Do note that since UTF-8 seems to be the dominant encoding for PHP applications, the DSN string must always be UTF-8 encoded. Here is a simple code snippet:

    $conn = new PDO( "sqlsrv:Server=(local);Database=AdventureWorks;Encrypt=true;ConnectionPooling=True;App=My Application {with}} spaces", $user, $password, array( PDO::ATTR_ERRMODE => PDO::ERRMODE_SILENT ) ); // "}" needs to be escaped

  2. Custom attribute PDO::SQLSRV_ATTR_DIRECT_QUERY: we are adding this new custom attribute to provide a developer more granular control of how the query and/or prepared statement is executed (affects PDO::prepare(), PDO::query() and PDOStatement::execute()). This is another change required by the design of the interaction between the PDO driver manager and the underlying driver. The reasons for making this change and how best to use it is probably a good topic for another blog, in short this change essentially means that the attribute controls whether a query is executed in the context of a prior query or a new context. For example, a temporary table created by one query can be used in another query that follows. Since this attribute is new and the default behavior is the same as in CTP1, this is non-breaking change.
  3. No objects as parameters for PDO_SQLSRV: PDO does not define an object data type and does not address how to handle situations when an object is passed in to an API. In CTP1, we noticed that we would fail if an object was passed in except if it was a DATETIME object. Now, in PDO_SQLSRV, if any object is passed in as a parameter then the API will fail – no exceptions. This could be a breaking change for some.
  4. Encoding for errors: In our previous release, errors were always returned in the original system encoding even if the application had changed the encoding (the data itself was always returned in the correct encoding). Now, even errors will be encoded per the encoding set for the connection. This could be a breaking change for some.

In addition to these changes, the SQLSRV extension “re-wiring” is now completed along with several bug fixes. So our CTP2 will have both extensions built from the same new refactored codebase, with some design changes listed above. We will update our documentation on MSDN to reflect these changes, of course, but this blog post gives you advance notice of what to expect in our CTP2 release and a chance to provide early feedback on our plans.

While the re-architecture offers many benefits in the long run, it adds a short term risk that SQLSRV can be regressed from our v1.1 release. We have a pretty comprehensive automated test suite for SQLSRV already, so we can compare the results with our test passes for v1.1. However, there’s always the possibility that we missed some test cases or some environment configuration or some DML/data pattern. It is for this reason that we are looking for broad participation for CTP2, especially those that have already deployed PHP applications with SQL Server.

We can share that we have implemented all the design changes and are in our stabilization phase. Our stabilization phase is when we run our tests suite then file/debug/triage/fix bugs, in an iterative process until we meet the release quality criteria. So far, the results are very encouraging and the trajectory indicates that we can release on June 21 – just over two weeks! Having mentioned this date, we want to be crystal clear that this will be a quality driven release rather than date driven. This means it can be later or even earlier.  🙂

We look forward to your feedback and your participation in the testing effort, it will be a huge help to get the code stable for production use.

SQL Server Driver for PHP team

Comments (6)
  1. The PDO exec/query methods really are not supposed to take objects as parameter values for fields. If an object is provided, the expectation is that it implements __toString() and thus be normalized to a string where needed. Otherwise an error should be generated, indicating an invalid value was supplied.

  2. Ashay says:

    Thanks for the information Ilia, we are considering this suggestion and will take it up offline with you on email as required.

  3. Raymond says:

    I think you need to add  a link on website so that other developer will know about the new PDO driver

  4. Raymond says:

    My only wish is that this Microsoft's PDO driver will not break from traditional PDO design or else it will be a a real pain to work with and hence lead to developer's rejecting it .

  5. Hi Ilia,

    What you say is essentially what we do. If an object is provided to a method that is not expecting one, PDO itself calls the object's _ToString() method and then sends the driver the string (either the caller specifies PDO::PARAM_STR or nothing). If the caller specifies either PDO::PARAM_INT or PDO::PARAM_BOOL, then PDO passes the object down to the driver. When the driver detects that the method argument passed in is an object, it will fail the method – in CTP1 we used to allow DATETIME objects to be accepted and now we don't.

    Since we don't know whether anyone has written code to this behavior discovered when trying out our CTP1 driver, this is our attempt to provide a "heads up" for a breaking change.

    The driver always attempts to generate a useful error message – as long as PDO::ATTR_ERRMODE is not PDO::ERRMODE_SILENT.

    Hope this helps.


  6. Hi Raymond,

    Great suggestion, I will communicate with the PHP core / site folks to see what we can do about this.

    Regarding your wish, we have tried our best to meet the intent of PDO and only making exceptions when other implementations already deviated or set a precedent. Ideally, for PDO to be considered a specification, it needs a lot more clarity and detail so that it is possible for each implementation to meet the guarantees offered by the API. When the PDO documentation (API docs, driver writer guide, etc.) was not clear enough, then we tried our best to meet the PDO intent by communicating with our partners including the PHP Core group. One great example of the former is the PDO::__construct() API change where our CTP1 implementation was completely within PDO definition but changed to the DSN in CTP2 based on feedback.

    I urge you to give our soon-to-be-released CTP2 and let us know where we deviated from the "traditional PDO design".



Comments are closed.

Skip to main content