Issue #263 Implement attachFiles()

Author: mikehaertl

README.md

@@ -261,6 +261,35 @@ if ($result === false) {
 }
 ```
 
+#### Attach Files
+
+Add file attachments to the document or to a specific page.
+
+```php
+use mikehaertl\pdftk\Pdf;
+
+$files = [
+    '/path/to/file1',
+    '/path/to/file2',
+]
+
+// Add files at the document level
+$pdf = new Pdf('/path/my.pdf');
+$result = $pdf->attachFiles($files)
+    ->saveAs('/path/withfiles.pdf');
+if ($result === false) {
+    $error = $pdf->getError();
+}
+
+// Add files to a specific page
+$pdf = new Pdf('/path/my.pdf');
+$page = 7;
+$result = $pdf->attachFiles($files, $page)
+    ->saveAs('/path/withfiles.pdf');
+if ($result === false) {
+    $error = $pdf->getError();
+}
+```
 #### Unpack Files
 
 Copy file attachments from a PDF to the given directory.

src/Pdf.php

@@ -231,6 +231,27 @@ public function burst($filepattern = null)
         return $this->execute();
     }
 
+    /**
+     * Attach files to the PDF
+     *
+     * @param array $files the list of full paths to the files to attach
+     * @param string $toPage the page to add the attachment to. If omitted the
+     * files are attached at the document level.
+     * @return bool whether the operation was successful
+     */
+    public function attachFiles($files, $toPage = null)
+    {
+        $this->constrainSingleFile();
+        if ($toPage !== null) {
+            $files[] = 'to_page';
+            $files[] = $toPage;
+        }
+        $this->getCommand()
+            ->setOperation('attach_files')
+            ->setOperationArgument($files, true);
+        return $this;
+    }
+
     /**
      * Copy all attachments from the PDF to the given directory
      *

tests/PdfTest.php

@@ -207,6 +207,7 @@ public function testCanShuffleFiles()
         $this->assertFileExists($file);
 
         $tmpFile = (string) $pdf->getTmpFile();
+        $this->assertFileExists($file);
         $this->assertEquals(
             "pdftk 'A'='$document1' 'B'='$document2' shuffle A1-5 2 3 4 Bend-2even A3-5east B4-8eveneast A1south 'output' '$tmpFile'",
             (string) $pdf->getCommand()
@@ -247,6 +248,46 @@ public function testCanBurstWithFilePattern()
         @unlink($dir . '/doc_data.txt');
     }
 
+    public function testAttachFiles()
+    {
+        $document = $this->getDocument1();
+        $file = $this->getOutFile();
+
+        $attachment1 = __DIR__ . '/files/testfile1.txt';
+        $attachment2 = __DIR__ . '/files/testfile2.txt';
+        $attachments = array($attachment1, $attachment2);
+
+        $pdf = new Pdf($document);
+        $this->assertInstanceOf('mikehaertl\pdftk\Pdf', $pdf->attachFiles($attachments));
+        $this->assertTrue($pdf->saveAs($file));
+        $this->assertFileExists($file);
+        $tmpFile = (string) $pdf->getTmpFile();
+        $this->assertEquals(
+            "pdftk 'A'='$document' 'attach_files' '$attachment1' '$attachment2' 'output' '$tmpFile'",
+            (string) $pdf->getCommand()
+        );
+    }
+
+    public function testAttachFilesToPage()
+    {
+        $document = $this->getDocument1();
+        $file = $this->getOutFile();
+
+        $attachment1 = __DIR__ . '/files/testfile1.txt';
+        $attachment2 = __DIR__ . '/files/testfile2.txt';
+        $attachments = array($attachment1, $attachment2);
+
+        $pdf = new Pdf($document);
+        $this->assertInstanceOf('mikehaertl\pdftk\Pdf', $pdf->attachFiles($attachments, 1));
+        $this->assertTrue($pdf->saveAs($file));
+        $this->assertFileExists($file);
+        $tmpFile = (string) $pdf->getTmpFile();
+        $this->assertEquals(
+            "pdftk 'A'='$document' 'attach_files' '$attachment1' '$attachment2' 'to_page' '1' 'output' '$tmpFile'",
+            (string) $pdf->getCommand()
+        );
+    }
+
     public function testUnpackFiles()
     {
         $document = $this->getDocument1();

tests/files/testfile1.txt

@@ -0,0 +1 @@
+Testfile 1

tests/files/testfile2.txt

@@ -0,0 +1 @@
+Testfile 1