mago-analyzer 1.20.0

A PHP static analyzer that can detect type errors in PHP code, and provide suggestions for fixing them.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

use mago_atom::Atom;
use mago_codex::metadata::function_like::FunctionLikeMetadata;
use mago_reporting::Annotation;
use mago_reporting::Issue;
use mago_span::Span;

use crate::code::IssueCode;
use crate::context::Context;
use crate::context::block::BlockContext;

/// Checks if using an experimental class-like from a non-experimental context and reports a warning.
pub fn check_experimental_class_like(
    context: &mut Context<'_, '_>,
    block_context: &BlockContext<'_>,
    class_name: Atom,
    span: Span,
) {
    if !context.settings.check_experimental {
        return;
    }

    let Some(metadata) = context.codebase.get_class_like(&class_name) else {
        return;
    };

    if !metadata.flags.is_experimental() {
        return;
    }

    if is_current_context_experimental(block_context) {
        return;
    }

    context.collector.report_with_code(
        IssueCode::ExperimentalUsage,
        Issue::warning(format!("Usage of experimental class-like `{}`.", metadata.original_name))
            .with_annotation(
                Annotation::primary(span)
                    .with_message(format!("`{}` is marked as `@experimental`.", metadata.original_name)),
            )
            .with_note("Experimental APIs may change or be removed without notice.")
            .with_help("Mark the current function or class as `@experimental` to suppress this warning."),
    );
}

/// Checks if calling an experimental function from a non-experimental context and reports a warning.
///
/// Accepts pre-resolved metadata to avoid redundant lookups.
pub fn check_experimental_function_with_metadata(
    context: &mut Context<'_, '_>,
    block_context: &BlockContext<'_>,
    metadata: &FunctionLikeMetadata,
    function_name: Atom,
    span: Span,
) {
    if !context.settings.check_experimental {
        return;
    }

    if !metadata.flags.is_experimental() {
        return;
    }

    if is_current_context_experimental(block_context) {
        return;
    }

    let display_name = metadata.original_name.unwrap_or(function_name);

    context.collector.report_with_code(
        IssueCode::ExperimentalUsage,
        Issue::warning(format!("Usage of experimental function `{display_name}`."))
            .with_annotation(
                Annotation::primary(span).with_message(format!("`{display_name}` is marked as `@experimental`.")),
            )
            .with_note("Experimental APIs may change or be removed without notice.")
            .with_help("Mark the current function or class as `@experimental` to suppress this warning."),
    );
}

/// Checks if using an experimental constant from a non-experimental context and reports a warning.
///
/// Accepts pre-resolved flags to avoid redundant lookups.
pub fn check_experimental_constant(
    context: &mut Context<'_, '_>,
    block_context: &BlockContext<'_>,
    flags: &mago_codex::metadata::flags::MetadataFlags,
    constant_name: &str,
    span: Span,
) {
    if !context.settings.check_experimental {
        return;
    }

    if !flags.is_experimental() {
        return;
    }

    if is_current_context_experimental(block_context) {
        return;
    }

    context.collector.report_with_code(
        IssueCode::ExperimentalUsage,
        Issue::warning(format!("Usage of experimental constant `{constant_name}`."))
            .with_annotation(
                Annotation::primary(span).with_message(format!("`{constant_name}` is marked as `@experimental`.")),
            )
            .with_note("Experimental APIs may change or be removed without notice.")
            .with_help("Mark the current function or class as `@experimental` to suppress this warning."),
    );
}

/// Checks if the current analysis context is itself marked as experimental.
fn is_current_context_experimental(block_context: &BlockContext<'_>) -> bool {
    if let Some(class_like) = block_context.scope.get_class_like()
        && class_like.flags.is_experimental()
    {
        return true;
    }

    // Check if the current function/method is experimental
    if let Some(function_meta) = block_context.scope.get_function_like()
        && function_meta.flags.is_experimental()
    {
        return true;
    }

    false
}