deprecate DummyPrintConnector in favour of MemoryPrintConnector (a rename w/ backwards compatibility)

Author: mike42

doc/FAQ.md

@@ -10,7 +10,7 @@ The purpose of this driver it to generate binary ESC/POS code, which is understo
 
 If the printer understands ESC/POS, and you know how to get raw binary data to it, then yes. Otherwise, no.
 
-The [list of printers that are known to work](https://github.com/mike42/escpos-php/blob/development/README.md#printers) is crowd-sourced. We appreciate it when developers try out the driver, then [file information on the bug tracker](https://github.com/mike42/escpos-php/issues/new) with some information about which features worked on their model of printer.
+The [list of printers that are known to work](https://github.com/mike42/escpos-php/blob/development/README.md#printers) is crowdsourced. We appreciate it when developers try out the driver, then [file information on the bug tracker](https://github.com/mike42/escpos-php/issues/new) with some information about which features worked on their model of printer.
 
 To see how well your printer works, first check that it supports ESC/POS, then begin by attempting to send the text "Hello World" to your printer on the command-line, from the computer that will run PHP.
 
@@ -24,7 +24,7 @@ If you encounter garbage output when you try to print images or special characte
 
 ## I have a printer that does not understand ESC/POS. Can I use this driver?
 
-No. The purpose of this driver it to generate binary ESC/POS code. If your printer doesn't understand that, then this code wont be much use to you.
+No. The purpose of this driver it to generate binary ESC/POS code. If your printer doesn't understand that, then this code won't be much use to you.
 
 Some printers do have an emulation mode for ESC/POS. The vendor docs will tell if this is the case, and how to enable it.
 
@@ -46,13 +46,13 @@ The connectors are-
 
 - `FilePrintConnector` and `NetworkPrintConnector` directly use files or network sockets.
 - `WindowsPrintConnector` and `CupsPrintConnector` tie in with Windows and Unix system printing.
-- `DummyPrintConnector` does not connect to a real printer, and can be used to save ESC/POS receipts to a database, for example.
+- `MemoryPrintConnector` does not connect to a real printer, and can be used capture ESC/POS receipts for testing or audit, for example.
 
-At this point, you might find that the way you would like to print is not supported by escpos-php. You can post your printing command as a feature request on the issue tracker.
+You might find that the way you would like to print is not supported by escpos-php. You can post your printing command as a feature request on the issue tracker.
 
 Lastly, you may run in to the final common trap:
 
-4. Your PHP is not running with the same sort of permissions as your login account. Again, no amount of PHP code can fix this. For example, on LAMP, your `www-data` user needs to be in the `lp` group, while on WAMP, `Local Service` account may run in to problems. SELinux and firewalls are also worth a look.
+4. Your PHP script is not running with the same sort of permissions as your login account. Again, it's not possible for the PHP code itself to fix this. For example, on LAMP, your `www-data` user needs to be in the `lp` group, while on WAMP, `Local Service` account may run in to problems. SELinux and firewalls are also worth a look.
 
 When printing fails, you can expect a PHP Exception that explains what went wrong. They are all clues:
 
@@ -66,7 +66,7 @@ Please file a bug if you think that there is a specific situation which escpos-p
 
 ## Can I print over the network?
 
-Certainly, as long as your printer is available over the network.
+Certainly, as long as your printer is available over the network!
 
 - `NetworkPrintConnector` will speak directly to an Ethernet-connected printer on port 9100.
 
@@ -75,7 +75,7 @@ For USB or Serial printers, you need to install the printer on a computer and th
 - `WindowsPrintConnector` will connect to Windows shared printers from Windows or Linux (Linux users will need Samba).
 - `CupsPrintConnector` will connect to CUPS-shared printers from Linux or Mac.
 
-Always start by testing your shared printer setup outside of escpos-php. The examples linked to in the README are commented with some example commands to get you started. Typically, networks, firewalls and permissions need to be set up.
+Always start by testing your shared printer setup outside of escpos-php. The examples linked to in the README are commented with some example commands to get you started. Typically, networks, firewalls and permissions all need to be set up.
 
 Once you have a working command to send text to your printer (from the PHP server), you are ready to use escpos-php.
 
@@ -127,7 +127,7 @@ First, ensure you have the Imagick plugin loaded. The driver will avoid a slower
 
 Next, connect over a faster interface. Serial printers have a low bit-rate, and the printer spends a lot of time waiting for data. If you have USB or Ethernet, then use it (note: storing graphics to the printer memory is not currently implemented).
 
-Lastly, the printer will go faster if you use less pixels. Since images are two-dimensional, scaling down by 50% removes 75% of the pixels. The driver can then print at a half the density, so that your lower resolution image appears the same size when printed.
+Lastly, images are sent uncompressed in ESC/POS, and you can speed up the transfer if you use fewer pixels. Images are two-dimensional, and scaling down by 50% removes 75% of the pixels. The driver has an option to print at half the density, so that the lower resolution image appears the same size when printed.
 
 ## How can I get the status of the printer?
 

example/specific/235-get-data.php

@@ -6,11 +6,11 @@
  */
 require __DIR__ . '/../../vendor/autoload.php';
 use Mike42\Escpos\Printer;
-use Mike42\Escpos\PrintConnectors\DummyPrintConnector;
+use Mike42\Escpos\PrintConnectors\MemoryPrintConnector;
 use Mike42\Escpos\CapabilityProfile;
 
 // Make sure you load a Star print connector or you may get gibberish.
-$connector = new DummyPrintConnector();
+$connector = new MemoryPrintConnector();
 $profile = CapabilityProfile::load("TSP600");
 $printer = new Printer($connector);
 $printer -> text("Hello world!\n");

src/Mike42/Escpos/PrintConnectors/DummyPrintConnector.php

@@ -17,65 +17,12 @@
 
 /**
  * Print connector that writes to nowhere, but allows the user to retrieve the
- * buffered data. Used for testing.
+ * buffered data.
+ *
+ * @deprecated Renamed to {@see MemoryPrintConnector}. This subclass is retained
+ *  for backwards compatibility and will be removed in a future major version.
+ *  Use MemoryPrintConnector in new code.
  */
-final class DummyPrintConnector implements PrintConnector
+class DummyPrintConnector extends MemoryPrintConnector
 {
-    /**
-     * @var array $buffer
-     *  Buffer of accumilated data.
-     */
-    private $buffer;
-
-    /**
-     * @var string data which the printer will provide on next read
-     */
-    private $readData;
-
-    /**
-     * Create new print connector
-     */
-    public function __construct()
-    {
-        $this -> buffer = [];
-    }
-
-    public function clear()
-    {
-        $this -> buffer = [];
-    }
-    
-    public function __destruct()
-    {
-        if ($this -> buffer !== null) {
-            trigger_error("Print connector was not finalized. Did you forget to close the printer?", E_USER_NOTICE);
-        }
-    }
-
-    public function finalize(): void
-    {
-        $this -> buffer = null;
-    }
-
-    /**
-     * @return string Get the accumulated data that has been sent to this buffer.
-     */
-    public function getData()
-    {
-        return implode($this -> buffer);
-    }
-
-    /**
-     * {@inheritDoc}
-     * @see PrintConnector::read()
-     */
-    public function read(int $len): bool|string
-    {
-        return $len >= strlen($this -> readData) ? $this -> readData : substr($this -> readData, 0, $len);
-    }
-
-    public function write(string $data): void
-    {
-        $this -> buffer[] = $data;
-    }
 }

src/Mike42/Escpos/PrintConnectors/MemoryPrintConnector.php

@@ -0,0 +1,82 @@
+<?php
+
+/**
+ * This file is part of escpos-php: PHP receipt printer library for use with
+ * ESC/POS-compatible thermal and impact printers.
+ *
+ * Copyright (c) 2014-2026 Michael Billington < michael.billington@gmail.com >,
+ * incorporating modifications by others. See CONTRIBUTORS.md for a full list.
+ *
+ * This software is distributed under the terms of the MIT license. See LICENSE.md
+ * for details.
+ */
+
+declare(strict_types=1);
+
+namespace Mike42\Escpos\PrintConnectors;
+
+/**
+ * Print connector that writes to nowhere, but allows the user to retrieve the
+ * buffered data. Useful for capturing raw ESC/POS output in memory - for
+ * inspection, for sending over your own transport, or for testing.
+ */
+class MemoryPrintConnector implements PrintConnector
+{
+    /**
+     * @var array $buffer
+     *  Buffer of accumilated data.
+     */
+    private $buffer;
+
+    /**
+     * @var string data which the printer will provide on next read
+     */
+    private $readData;
+
+    /**
+     * Create new print connector
+     */
+    public function __construct()
+    {
+        $this -> buffer = [];
+    }
+
+    public function clear()
+    {
+        $this -> buffer = [];
+    }
+
+    public function __destruct()
+    {
+        if ($this -> buffer !== null) {
+            trigger_error("Print connector was not finalized. Did you forget to close the printer?", E_USER_NOTICE);
+        }
+    }
+
+    public function finalize(): void
+    {
+        $this -> buffer = null;
+    }
+
+    /**
+     * @return string Get the accumulated data that has been sent to this buffer.
+     */
+    public function getData()
+    {
+        return implode($this -> buffer);
+    }
+
+    /**
+     * {@inheritDoc}
+     * @see PrintConnector::read()
+     */
+    public function read(int $len): bool|string
+    {
+        return $len >= strlen($this -> readData) ? $this -> readData : substr($this -> readData, 0, $len);
+    }
+
+    public function write(string $data): void
+    {
+        $this -> buffer[] = $data;
+    }
+}

test/unit/AuresCustomerDisplayTest.php

@@ -1,7 +1,7 @@
 <?php
 
 use Mike42\Escpos\Devices\AuresCustomerDisplay;
-use Mike42\Escpos\PrintConnectors\DummyPrintConnector;
+use Mike42\Escpos\PrintConnectors\MemoryPrintConnector;
 use Mike42\Escpos\CapabilityProfile;
 
 class AuresCustomerDisplayTest extends PHPUnit\Framework\TestCase
@@ -12,7 +12,7 @@ class AuresCustomerDisplayTest extends PHPUnit\Framework\TestCase
     protected function setUp(): void
     {
         /* Print to nowhere- for testing which inputs are accepted */
-        $this -> outputConnector = new DummyPrintConnector();
+        $this -> outputConnector = new MemoryPrintConnector();
         $profile = CapabilityProfile::load('OCD-300');
         $this -> printer = new AuresCustomerDisplay($this -> outputConnector, $profile);
     }

test/unit/EscposPrintBufferTest.php

@@ -10,7 +10,7 @@
  * - http://clagnut.com/blog/2380/ (mirrored from the English Wikipedia)
  */
 use Mike42\Escpos\Printer;
-use Mike42\Escpos\PrintConnectors\DummyPrintConnector;
+use Mike42\Escpos\PrintConnectors\MemoryPrintConnector;
 
 class EscposPrintBufferTest extends PHPUnit\Framework\TestCase
 {
@@ -19,7 +19,7 @@ class EscposPrintBufferTest extends PHPUnit\Framework\TestCase
 
     protected function setUp(): void
     {
-        $this -> outputConnector = new DummyPrintConnector();
+        $this -> outputConnector = new MemoryPrintConnector();
         $printer = new Printer($this -> outputConnector);
         $this -> buffer = $printer -> getPrintBuffer();
     }

test/unit/EscposTest.php

@@ -1,6 +1,6 @@
 <?php
 use Mike42\Escpos\Printer;
-use Mike42\Escpos\PrintConnectors\DummyPrintConnector;
+use Mike42\Escpos\PrintConnectors\MemoryPrintConnector;
 use Mike42\Escpos\EscposImage;
 use Mike42\Escpos\CapabilityProfile;
 
@@ -12,7 +12,7 @@ class EscposTest extends PHPUnit\Framework\TestCase
     protected function setUp(): void
     {
         /* Print to nowhere- for testing which inputs are accepted */
-        $this -> outputConnector = new DummyPrintConnector();
+        $this -> outputConnector = new MemoryPrintConnector();
         $this -> printer = new Printer($this -> outputConnector);
     }
 

test/unit/Experimental/Unifont/UnifontPrintBufferTest.php

@@ -2,7 +2,7 @@
 
 namespace Mike42\Escpos\Experimental\Unifont;
 
-use Mike42\Escpos\PrintConnectors\DummyPrintConnector;
+use Mike42\Escpos\PrintConnectors\MemoryPrintConnector;
 use Mike42\Escpos\Printer;
 use PHPUnit\Framework\TestCase;
 
@@ -13,7 +13,7 @@ class UnifontPrintBufferTest extends TestCase
 
     protected function setUp(): void
     {
-        $this -> outputConnector = new DummyPrintConnector();
+        $this -> outputConnector = new MemoryPrintConnector();
         $this -> printer = new Printer($this -> outputConnector);
         $filename = tempnam(sys_get_temp_dir(), "escpos-php-");
         $glyphs = [

test/unit/MultiplePrintConnectorTest.php

@@ -1,6 +1,6 @@
 <?php
 
-use Mike42\Escpos\PrintConnectors\DummyPrintConnector;
+use Mike42\Escpos\PrintConnectors\MemoryPrintConnector;
 use Mike42\Escpos\PrintConnectors\MultiplePrintConnector;
 use Mike42\Escpos\Printer;
 
@@ -9,8 +9,8 @@ class MultiplePrintConnectorTest extends PHPUnit\Framework\TestCase
     public function testOnePrinter()
     {
         // Set up connector which goes to multiple printers
-        $kitchenPrinter = new DummyPrintConnector();
-        $barPrinter = new DummyPrintConnector();
+        $kitchenPrinter = new MemoryPrintConnector();
+        $barPrinter = new MemoryPrintConnector();
         $connector = new MultiplePrintConnector($kitchenPrinter, $barPrinter);
         // Print something
         $printer = new Printer($connector);