Null Values in Chart

Based on PR PHPOffice#2854 by @Tom-Magill.

Author: oleibman

src/PhpWord/Style/Chart.php

@@ -149,6 +149,14 @@ class Chart extends AbstractStyle
      */
     private $gridX = false;
 
+    /**
+     * How to display blank values (nulls) in series data.
+     * Options: 'gap' (break line), 'span' (connect line), 'zero' (plot as zero).
+     *
+     * @var string
+     */
+    private $displayBlanksAs = 'gap'; // Default to gap
+
     /**
      * Create a new instance.
      *
@@ -548,4 +556,31 @@ public function setShowGridX($value = true)
 
         return $this;
     }
+
+    /**
+     * Set display blanks as option.
+     *
+     * @param string $value 'gap', 'span', or 'zero'
+     *
+     * @return self
+     */
+    public function setDisplayBlanksAs($value)
+    {
+        $validValues = ['gap', 'span', 'zero'];
+        if (in_array($value, $validValues, true)) {
+            $this->displayBlanksAs = $value;
+        }
+
+        return $this;
+    }
+
+    /**
+     * Get display blanks as option.
+     *
+     * @return string
+     */
+    public function getDisplayBlanksAs()
+    {
+        return $this->displayBlanksAs;
+    }
 }

src/PhpWord/Writer/Word2007/Part/Chart.php

@@ -205,6 +205,16 @@ private function writePlotArea(XMLWriter $xmlWriter): void
         }
 
         $xmlWriter->endElement(); // c:plotArea
+
+        $xmlWriter->startElement('c:plotVisOnly');
+        $xmlWriter->writeAttribute('val', '1');
+        $xmlWriter->endElement();
+
+        $displayBlanksAs = method_exists($style, 'getDisplayBlanksAs') ? $style->getDisplayBlanksAs() : 'gap';
+
+        $xmlWriter->startElement('c:dispBlanksAs');
+        $xmlWriter->writeAttribute('val', $displayBlanksAs);
+        $xmlWriter->endElement();
     }
 
     /**
@@ -314,13 +324,17 @@ private function writeSeriesItem(XMLWriter $xmlWriter, $type, $values): void
         foreach ($values as $value) {
             $xmlWriter->startElement('c:pt');
             $xmlWriter->writeAttribute('idx', $index);
-            if (\PhpOffice\PhpWord\Settings::isOutputEscapingEnabled()) {
-                $xmlWriter->writeElement('c:v', $value);
-            } else {
-                $xmlWriter->startElement('c:v');
-                $xmlWriter->writeRaw($value);
-                $xmlWriter->endElement(); // c:v
+
+            if ($value !== null) {
+                if (\PhpOffice\PhpWord\Settings::isOutputEscapingEnabled()) {
+                    $xmlWriter->writeElement('c:v', $value);
+                } else {
+                    $xmlWriter->startElement('c:v');
+                    $xmlWriter->writeRaw($value);
+                    $xmlWriter->endElement(); // c:v
+                }
             }
+
             $xmlWriter->endElement(); // c:pt
             ++$index;
         }

tests/PhpWordTests/Writer/Word2007/Part/ChartNullHandlingTest.php

@@ -0,0 +1,77 @@
+<?php
+
+namespace PhpOffice\PhpWord\Tests\Writer\Word2007\Part;
+
+use PhpOffice\PhpWord\Element\Chart;
+use PhpOffice\PhpWord\Shared\XMLWriter;
+use PhpOffice\PhpWord\Writer\Word2007\Part\Chart as ChartWriter;
+use PHPUnit\Framework\TestCase;
+use ReflectionClass;
+
+class ChartNullHandlingTest extends TestCase
+{
+    /**
+     * Test that the Style class correctly sets/gets the property.
+     */
+    public function testSetGetDisplayBlanksAs(): void
+    {
+        // Note: Pass empty arrays for categories/values to avoid constructor errors
+        $chart = new Chart('line', [], []);
+        $style = $chart->getStyle();
+
+        // 1. Default should be 'gap'
+        self::assertEquals('gap', $style->getDisplayBlanksAs());
+
+        // 2. Test setting 'span'
+        $style->setDisplayBlanksAs('span');
+        self::assertEquals('span', $style->getDisplayBlanksAs());
+
+        // 3. Test invalid value (should remain 'span')
+        $style->setDisplayBlanksAs('invalid_option');
+        self::assertEquals('span', $style->getDisplayBlanksAs());
+    }
+
+    public function testWriteChartHandlesNullsAndGaps(): void
+    {
+        // 1. Setup Data
+        $categories = ['Jan', 'Feb', 'Mar'];
+        $values = [10, null, 20];
+        $seriesNames = ['My Series']; // <--- ADD THIS
+
+        // 2. Create Chart with Series Name
+        $chart = new Chart('line', $categories, $values, $seriesNames);
+        $chart->getStyle()->setDisplayBlanksAs('gap');
+
+        // 3. Setup Writer
+        $xmlWriter = new XMLWriter();
+        $chartWriter = new ChartWriter();
+
+        // Mock the parent writer
+        $chartWriter->setParentWriter($this->createMock(\PhpOffice\PhpWord\Writer\Word2007::class));
+
+        // 4. Inject Chart into Writer
+        $reflectionWriter = new ReflectionClass(ChartWriter::class);
+        $elementProperty = $reflectionWriter->getProperty('element');
+        $elementProperty->setAccessible(true);
+        $elementProperty->setValue($chartWriter, $chart);
+
+        // 5. Run
+        $method = $reflectionWriter->getMethod('writeChart');
+        $method->setAccessible(true);
+        $method->invokeArgs($chartWriter, [$xmlWriter]);
+
+        $xml = $xmlWriter->getData();
+
+        // --- ASSERTIONS ---
+        self::assertStringContainsString('<c:dispBlanksAs val="gap"/>', $xml);
+
+        // Check for the empty point (null value)
+        self::assertMatchesRegularExpression('/<c:pt idx="1"\s*\/?>/', $xml);
+
+        // Ensure no zero value was written for index 1
+        self::assertDoesNotMatchRegularExpression(
+            '/<c:pt idx="1"[^>]*>.*?<c:v>0<\/c:v>.*?<\/c:pt>/s',
+            $xml
+        );
+    }
+}